home *** CD-ROM | disk | FTP | other *** search
/ The CICA Windows Explosion! / The CICA Windows Explosion! - Disc 2.iso / programr / lxtw104.zip / SXT.DOC < prev    next >
Text File  |  1994-09-11  |  198KB  |  4,576 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.                   SXT (TM) SOFTWARE EXPLORATION TOOLS
  11.  
  12.  
  13.  
  14.                   CXT (TM) C EXPLORATION TOOLS
  15.  
  16.                     * CFT (TM) C FUNCTION TREE GENERATOR
  17.                     * CST (TM) C STRUCTURE TREE GENERATOR
  18.  
  19.  
  20.                   DXT (TM) DBASE EXPLORATION TOOLS
  21.  
  22.                     * DFT (TM) DBASE FUNCTION TREE GENERATOR
  23.  
  24.  
  25.                   FXT (TM) FORTRAN EXPLORATION TOOLS
  26.  
  27.                     * FFT (TM) FORTRAN FUNCTION TREE GENERATOR
  28.  
  29.  
  30.                   LXT (TM) LISP EXPLORATION TOOLS
  31.  
  32.                     * LFT (TM) LISP FUNCTION TREE GENERATOR
  33.  
  34.  
  35.  
  36.                   (SXT command-line and SXTWIN Windows versions)
  37.  
  38.  
  39.                   September 1994
  40.  
  41.                   Copyright (C) Juergen Mueller (J.M.) 1988-1994.
  42.                   All rights reserved world-wide.
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.                                       - 1 -
  62.  
  63.  
  64.                              DISCLAIMER OF WARRANTY
  65.  
  66.         THIS  SOFTWARE  AND  ACCOMPANYING  WRITTEN  MATERIALS  (INCLUDING
  67.         INSTRUCTIONS FOR USE) IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF
  68.         ANY  KIND,   EITHER  EXPRESS  OR  IMPLIED,   INCLUDING,   WITHOUT
  69.         LIMITATION,  THE IMPLIED WARRANTIES OF MERCHANTIBILITY OR FITNESS
  70.         FOR  A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE RESULTS AND
  71.         PERFORMANCE OF THE SOFTWARE IS WITH YOU.
  72.  
  73.         IN NO EVENT WILL THE AUTHOR AND COPYRIGHT HOLDER  BE  LIABLE  FOR
  74.         DAMAGES,  INCLUDING  ANY  LOST  PROFITS,  LOST  MONIES,  OR OTHER
  75.         DIRECT,  INDIRECT,  GENERAL,  SPECIAL,  INCIDENTAL,  EXEMPLARY OR
  76.         CONSEQUENTIAL  DAMAGES  ARISING  IN  ANY  WAY  OUT  OF THE USE OR
  77.         INABILITY TO USE THIS PROGRAM (INCLUDING,  BUT  NOT  LIMITED  TO,
  78.         PROCUREMENT   OF   SUBSTITUTE   GOODS   OR   SERVICES,   BUSINESS
  79.         INTERRUPTION,  LOSS OF DATA OR DATA BEING RENDERED INACCURATE  OR
  80.         LOSSES  SUSTAINED  BY  YOU  OR  THIRD PARTIES OR A FAILURE OF THE
  81.         PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS) AND ON ANY THEORY  OF
  82.         LIABILITY, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR
  83.         FOR ANY CLAIM BY ANY OTHER PARTY.
  84.  
  85.  
  86.                                  ACKNOWLEDGEMENT
  87.  
  88.         BY  USING  THIS  SOFTWARE YOU ACKNOWLEDGE THAT YOU HAVE READ THIS
  89.         LIMITED WARRANTY AND ACCOMPANYING  REMARKS,  UNDERSTAND  IT,  AND
  90.         AGREE  TO  BE  BOUND BY ITS TERMS AND CONDITIONS.  YOU ALSO AGREE
  91.         THAT THIS IS THE COMPLETE AND EXCLUSIVE  STATEMENT  OF  AGREEMENT
  92.         BETWEEN   THE  PARTIES  AND  SUPERSEDE  ALL  PROPOSALS  OR  PRIOR
  93.         AGREEMENTS, ORAL OR WRITTEN, AND ANY OTHER COMMUNICATIONS BETWEEN
  94.         THE PARTIES  RELATING  TO  THE  SUBJECT  MATTER  OF  THE  LIMITED
  95.         WARRANTY.
  96.  
  97.  
  98.         You  are expressly prohibited from selling this software or parts
  99.         of it in any form,  circulate it in any  incomplete  or  modified
  100.         form,  distribute  it  with another product (except on CD-ROM) or
  101.         removing this notice.  No one may modify  or  patch  any  of  the
  102.         executable  files  in  any  way,  including,  but not limited to,
  103.         decompiling,  disassembling or otherwise reverse engineering this
  104.         software in whole or part.
  105.  
  106.         The  documentation  may be distributed verbatim,  but changing is
  107.         not allowed. The informations and specifications in this document
  108.         are subject to change without notice.
  109.  
  110.         THIS  VERSION  OF  THE  DOCUMENTATION,   SOFTWARE  AND  COPYRIGHT
  111.         SUPERSEDES  ALL PREVIOUS VERSIONS.  THIS SOFTWARE AND ITS RELATED
  112.         DOCUMENTATION MAY CHANGE WITHOUT NOTICE.
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.                                       - 2 -
  123.  
  124.  
  125.         This software and documentation is Copyright (C) by
  126.  
  127.                   Juergen Mueller
  128.                   Aldingerstrasse 22
  129.                   D-70806 Kornwestheim
  130.                   GERMANY
  131.  
  132.                   Email address: juergen.mueller@isw.uni-stuttgart.de
  133.  
  134.  
  135.         There are no relations between the authors professional work  and
  136.         the SXT development. SXT is an independent private project of the
  137.         author.
  138.  
  139.  
  140.  
  141.  
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.                                       - 3 -
  184.  
  185.  
  186.                                      LICENSE
  187.  
  188.         This  version of the SXT Software Exploration Tools is NOT public
  189.         domain or free software, but is being distributed as SHAREWARE.
  190.  
  191.         Non-registered users of  this  software  are  granted  a  limited
  192.         license  for  a 30-day evaluation period starting from the day of
  193.         the first use to make an evaluation copy for trial  use  for  the
  194.         express  purpose of determining whether this software is suitable
  195.         for their needs.  At the end of  this  trial  period  you  should
  196.         either register your copy or discontinue using this software. The
  197.         use  of  unregistered  copies  of  this software,  outside of the
  198.         initial 30-day  trial,  by  any  person,  business,  corporation,
  199.         government agency or any other entity is strictly prohibited.
  200.  
  201.         This means that if you use this software, then you should pay for
  202.         your  copy.   This  software  is  NOT  free,  but  you  have  the
  203.         opportunity to try it before you buy it.  Either pay for  it,  or
  204.         quit  using  it.  A registration entitles you to use your copy of
  205.         this software on any and all computers available to you. If other
  206.         people  have  access  to  this  software  or  may  use  it,  then
  207.         additional copies or a site license should be purchased.
  208.  
  209.         All  users  are  granted  a limited license to copy this software
  210.         only for the trial  use  of  others  and  subject  to  the  above
  211.         limitations.  This license does NOT include distribution, selling
  212.         or copying of this software package in connection with any  other
  213.         product  or  service  or  for  distribution  in any incomplete or
  214.         modified form. Operators of electronic bulletin board systems and
  215.         software servers (like INTERNET FTP-Servers)  are  encouraged  to
  216.         post this software for downloading by their users, as long as the
  217.         above conditions are met.
  218.  
  219.         This  package  is  expected  to  be  distributed by shareware and
  220.         freeware channels,  but the fees paid  for  "distribution"  costs
  221.         (e.g.   disk,   CD-ROM)   are   strictly  exchanged  between  the
  222.         distributor and the recipient, and the author makes no express or
  223.         implied  warranties  about  the  quality  or  integrity  of  such
  224.         indirectly acquired copies. Distributors and users may obtain the
  225.         package  directly  from  the  author  by  following  the ordering
  226.         procedures in the REGISTER files.
  227.  
  228.  
  229.                               REGISTRATION REMINDER
  230.  
  231.         Unregistered copies of this software are 100% fully functional. I
  232.         make them this way so that you can have a real look at them,  and
  233.         then decide whether they fit your needs or not. This work depends
  234.         on your honesty.  If you use it, I expect you to pay for it. When
  235.         you pay for the shareware you like,  you  are  voting  with  your
  236.         pocketbook,  and  will encourage me and others to develop more of
  237.         these kinds of products.
  238.  
  239.  
  240.                  THANK YOU FOR SUPPORTING THE SHAREWARE CONCEPT
  241.  
  242.  
  243.  
  244.                                       - 4 -
  245.  
  246.  
  247.                   TABLE OF CONTENTS
  248.  
  249.                   1    THE SXT SOFTWARE EXPLORATION TOOLS
  250.                   2    GENERAL INTRODUCTION
  251.                   3    PROGRAM DESCRIPTION
  252.                   4    LANGUAGE IMPLEMENTATIONS
  253.                   4.1  C-LANGUAGE IMPLEMENTATION AND C-PREPROCESSOR
  254.                   4.2  C++ LANGUAGE IMPLEMENTATION
  255.                   4.3  DBASE SOURCE CODE
  256.                   4.4  FORTRAN SOURCE CODE
  257.                   4.5  LISP SOURCE CODE
  258.                   4.6  ASSEMBLER SOURCE CODE
  259.                   5    DATABASE GENERATION
  260.                   6    PROGRAM LIMITATIONS
  261.                   7    IMPROVING EXECUTION SPEED
  262.                   8    COMMAND LINE SYNTAX DESCRIPTION
  263.                   9    OUTPUT DESCRIPTION AND INTERPRETATION
  264.                   10   INTEGRATION INTO PROGRAM DEVELOPMENT ENVIRONMENTS
  265.                   11   TOOLS FOR DATABASE PROCESSING
  266.                   12   TROUBLE SHOOTING
  267.                   13   FREQUENTLY ASKED QUESTIONS
  268.                   14   REFERENCES
  269.                   15   TRADEMARKS
  270.  
  271.                   APPENDIX 1: C-PRECOMPILER DEFINES
  272.                   APPENDIX 2: RESERVED C/C++ KEYWORDS
  273.                   APPENDIX 3: RESERVED FORTRAN KEYWORDS
  274.                   APPENDIX 4: EFFICIENCY
  275.                   APPENDIX 5: REVIEWS
  276.                   APPENDIX 6: SYSTEM REQUIREMENTS
  277.                   APPENDIX 7: INSTALLATION
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.                                       - 5 -
  306.  
  307.  
  308.         1    THE SXT SOFTWARE EXPLORATION TOOLS
  309.  
  310.         The SXT Software Exploration Tools are a collection  of  software
  311.         analysis  tools  providing  a similar functionality for different
  312.         programming languages.
  313.  
  314.         The following packages are currently available:
  315.  
  316.         * CXT - C Exploration Tools:
  317.           CFT - C Function Tree Generator
  318.              Tool to analyse and display the function call  relationships
  319.              within the source code of C/C++ programs.
  320.           CST - C Structure Tree Generator
  321.              Tool    to   analyse   and   display   the   structure/class
  322.              relationships within the source code of C/C++ programs.
  323.  
  324.         * DXT - DBASE Exploration Tools:
  325.           DFT - DBASE Function Tree Generator
  326.              Tool to analyse and display the function call  relationships
  327.              within the source code of DBASE,  CLIPPER, FOXBASE and other
  328.              XBASE-like programs.
  329.  
  330.         * FXT - FORTRAN Exploration Tools:
  331.           FFT - FORTRAN Function Tree Generator
  332.              Tool to analyse and display the function call  relationships
  333.              within the source code of FORTRAN programs.
  334.  
  335.         * LXT - LISP Exploration Tools:
  336.           LFT - LISP Function Tree Generator
  337.              Tool  to analyse and display the function call relationships
  338.              within the source code of LISP and SCHEME programs.
  339.  
  340.         Each  of  these  packages  consists  of  the   analysis   program
  341.         ("Analyser")  and  a recall program ("Navigator") to retrieve the
  342.         analysis  results  which  can  be  stored  in  a  database,  plus
  343.         documentation and additional macros to integrate these tools into
  344.         popular editors like BRIEF, QEDIT or MicroEMACS.
  345.  
  346.         Each of these packages is available for the following systems:
  347.  
  348.              * DOS real mode               (shareware release)
  349.              * DOS 386 protected mode      (registered users only)
  350.              * WINDOWS NT text mode        (registered users only)
  351.              * OS/2 text mode              (registered users only)
  352.              * Windows 3.1                 (shareware release)
  353.              * Windows 32 bit (Win32s)     (registered users only)
  354.  
  355.         There  are  no  differences  in  the  functionality  between  the
  356.         versions for the different systems.
  357.  
  358.         There are no plans to port the SXT programs to other platforms or
  359.         operating systems like Apple MacIntosh, UNIX (SCO, Solaris,  AIX,
  360.         HP-UX,  Linux,  ...),  Atari or Amiga. The source code of the SXT
  361.         programs is not available.
  362.  
  363.  
  364.  
  365.  
  366.                                       - 6 -
  367.  
  368.  
  369.         IMPORTANT NOTICE
  370.  
  371.         Although this document is mainly based on the description for the
  372.         CXT programs CFT and CST (which were up to version 2.13 the  only
  373.         public  available SXT programs) and therefore very C/C++ related,
  374.         the description  applies  in  the  same  way  to  all  other  SXT
  375.         packages.  The  names  CXT/CXTWIN  resp.  CFT/CST,  CFTN/CSTN and
  376.         CFTWIN/CSTWIN can  be  simply  exchanged  by  the  similar  other
  377.         product  names  DXT,  FXT or LXT.  Where necessary,  the specific
  378.         differences of the SXT packages are described.  I  have  done  it
  379.         this  way  to ensure an overall consistency,  to keep all related
  380.         things together  and  to  reduce  the  efforts  for  writing  and
  381.         maintaining this document.
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.  
  408.  
  409.  
  410.  
  411.  
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426.  
  427.                                       - 7 -
  428.  
  429.  
  430.         2    GENERAL INTRODUCTION
  431.  
  432.         The  SXT  programs are powerful program development,  maintenance
  433.         and  documentation  tools.   They  are  primarily  intended   for
  434.         analysing  large  programs,   where  it  is  difficult,   if  not
  435.         impossible, for the programmer to find the structure of the whole
  436.         program.   They  allow  the  analysis  of  the  source  code   of
  437.         applications,  no  matter  how  big or complex they are.  The SXT
  438.         programs are also very useful to explore unknown source code  and
  439.         to  get  complete  overview  about  its  internal structure.  The
  440.         re-engineering of old and/or undocumented source code becomes  an
  441.         easy  task with these programs.  The tools help the programmer to
  442.         analyse,  identify,  locate and  access  all  parts  of  a  large
  443.         software  system.  They  are  designed to support software reuse,
  444.         maintenance and reliability.
  445.  
  446.         By preprocessing,  scanning  and  analysing  the  entire  program
  447.         source  code  as a single unit,  these programs build an internal
  448.         representation of the function call  hierarchy  (CFT,  DFT,  FFT,
  449.         LFT)  and  of  the data structure relations (CST).  The resulting
  450.         output shows from a global perspective the interdependencies  and
  451.         hierarchical structure between the functions or data types of the
  452.         whole, multi file, software project. Several features and options
  453.         allow  the  user  to customise the generated hierarchy tree chart
  454.         output and to get a large set of useful  informations  about  the
  455.         source code. The hierarchy structure is always up-to-date because
  456.         it  relies  on  the original source code as the primary source of
  457.         information.  Written software documentation often  differs  from
  458.         that what really has been coded, so the source code itself is the
  459.         ultimate documentation.
  460.  
  461.         An  important  feature is the database generation.  It allows the
  462.         recalling of informations without reprocessing the  source  code.
  463.         The  database  can  again  be  read  in by CFT and CST to produce
  464.         different outputs or to add new files to  the  database.  Special
  465.         recall  programs  called  CFTN  and CSTN allow fast searching for
  466.         items in the database.  These programs can  be  used  within  any
  467.         environment,  for  example on the DOS command line or from inside
  468.         editors like BRIEF,  QEDIT or MicroEMACS (DOS  and  WINDOWS),  to
  469.         provide  a full software project management system with access to
  470.         all functions  and  data  types  with  just  a  keystroke.  These
  471.         features  make  a  comfortable "hypertext source code browser and
  472.         locator" system out of  your  editor.  A  project  consisting  of
  473.         several   files  appears  to  the  developer  as  if  it  were  a
  474.         'whole-part' of software. The developer can walk through programs
  475.         and trace the logic without having to  memorize  the  directories
  476.         and files where functions or data types are defined and called.
  477.  
  478.         Displaying   and  printing  a  graphical  representation  of  the
  479.         analysis results as a call graph is not  supported  bye  the  SXT
  480.         programs  but  owners  of  RATIONAL  ROSE,  a  powerful  software
  481.         development  case  tool  supporting  the  Booch   Object-Oriented
  482.         Analysis  and  Design  (OOAD) method,  can use this tool for such
  483.         purposes.  The SXT programs can generate compatible output  which
  484.         can  be  imported  by  Rational Rose.  See option -RATIONAL for a
  485.         detailed description.
  486.  
  487.  
  488.                                       - 8 -
  489.  
  490.  
  491.  
  492.         Listings of all functions/data types  and  source  files  can  be
  493.         written  as  formatted  ASCII text files and can be used as input
  494.         for  other  programs  like   word   processors   or   spreadsheet
  495.         calculators.
  496.  
  497.         A  useful  option  of CST is the possibility to generate a source
  498.         file  with  which  size  and   byte   offset   calculations   for
  499.         structures/unions and their members can be performed. This option
  500.         is  useful  especially  to support any kind of error searching or
  501.         hardware  debugging,  for  example  with  an  ICE,   or  if  data
  502.         structures  have  to  be  exchanged  between  different  hardware
  503.         platforms.
  504.  
  505.         CFT can also be used to analyse "C"-like languages  as  they  are
  506.         used  by  several  commercial  programs.  The  macro  programming
  507.         languages of the BRIEF, EPSILON and ME editors are such languages
  508.         and can be handled by CFT.
  509.  
  510.         The resulting output files can be used for various purposes  like
  511.         development  or documentation.  For registered users there are no
  512.         restriction limits in using them for their own work.
  513.  
  514.         CFT and CST have been used  and  tested  since  1989  in  several
  515.         projects  with applications ranging from single source files over
  516.         medium sized projects (like CFT,  CST and  the  other  SXT  tools
  517.         themselves)  up  to very large software projects with hundreds of
  518.         source and include files (mixed C and assembler code),  more than
  519.         6 MB of source code,  more than 210000 lines,  2300 functions and
  520.         700 data types.
  521.  
  522.         A lot of public available C/C++  sources  (e.g.  GNU-C  compiler,
  523.         GNU-C library,  GNU-EMACS,  MicroEMACS, NCSA TCP/IP communication
  524.         software package, SUIT - The Simple User Interface Toolkit, NIHCL
  525.         - The  National  Institute  of  Health  C++  class  library,  F2C
  526.         Fortran-to-C translator,  several projects from Dr. Dobbs Journal
  527.         (DFLAT,  BOB),  Microsoft sample code (MFC  1.0  and  2.0))  were
  528.         processed   (with   sometimes  surprising  results!)  during  the
  529.         development and have been used to test and improve the  features,
  530.         reliability,  correctness, robustness and execution speed of CFT,
  531.         CST and their related utilities.
  532.  
  533.         Although the other SXT packages are much newer than CFT and  CST,
  534.         they all are closely related.  The CXT tools are used as the base
  535.         for all other packages.
  536.  
  537.  
  538.  
  539.  
  540.  
  541.  
  542.  
  543.  
  544.  
  545.  
  546.  
  547.  
  548.  
  549.                                       - 9 -
  550.  
  551.  
  552.         3    PROGRAM DESCRIPTION
  553.  
  554.         CFT builds a hierarchy tree chart  of  every  function  with  the
  555.         called functions in it's own function block.  These functions are
  556.         again used as a starting point for  subsequent  function  blocks.
  557.         Starting  the tree chart with the "main"-function it will display
  558.         the complete function  flow  chart  and  the  function  hierarchy
  559.         dependency  of  the  whole  application  with  all  user  defined
  560.         functions and the called library functions.  Prototyped but never
  561.         defined or called functions are also detected. Recursive calls of
  562.         functions  are  recognised and displayed,  even over several call
  563.         levels.  Repeated calls of previously displayed functions in  the
  564.         output tree chart are detected and a message will be given with a
  565.         reference to their first appearance.  This prevents the output of
  566.         complete subtrees displayed earlier. Overloaded C++ functions and
  567.         operators  are  recognised  and  displayed  with  the  number  of
  568.         overloadings.
  569.  
  570.         CST  acts  similar  to  CFT but it works on data types like basic
  571.         types,  structures,  unions,  enumerations and C++  classes.  CST
  572.         builds  a  hierarchy tree chart of every structure and union data
  573.         type with their internal elements and their related  data  types.
  574.         If these data types are again structures,  unions or classes, the
  575.         substructures will again be displayed.  CST recognises data types
  576.         defined by 'typedef' and derived from other data types.  The type
  577.         names corresponding to the same basic type are displayed  in  the
  578.         output  file  as  'alias'  names for their common basic data type
  579.         name.  Every feature of  CFT  like  the  detection  of  recursive
  580.         declared   structures   and  unions,   references  to  previously
  581.         displayed data types and others are available and act similar.
  582.  
  583.         Every function (CFT) and data type (CST) can  be  displayed  with
  584.         the  name  of  the  source  file  and the line number where it is
  585.         defined.  The output can be customised to display the tree  chart
  586.         as a call-tree ("CALLER-CALLEE"-relation: "WHO CALLS WHOM") or as
  587.         a   caller-tree  ("CALLEE-CALLER"-relation:  "WHO  IS  CALLED  BY
  588.         WHOM"). This feature allows the user to determine which functions
  589.         are called from  a  specific  function  or  which  functions  are
  590.         callers of a specific function.
  591.  
  592.         The  function  and  data  type extraction from the source code is
  593.         done by scanning and parsing the source.  There is absolutely  no
  594.         need  for  the  programmer  to  mark  functions  or data types of
  595.         interest,  for  example  with  special  keywords,   starting  the
  596.         definitions  at  the  beginning  of  a  line  or  to use comments
  597.         containing special marks,  as it is necessary  for  other  source
  598.         code analysers and browsers.  CFT, CST and the other SXT programs
  599.         do not need these work-arounds,  any source code can be processed
  600.         without previous work.  These tools are also compiler independent
  601.         because they can be customised to support any kind of compiler.
  602.  
  603.         Since the SXT programs always  make  a  static  analysis  of  the
  604.         program  source code,  they are not able to detect references due
  605.         to the expansion of a macro definition during runtime.  This  has
  606.         to  be  considered  for  DBASE and LISP programs which allow such
  607.         dynamic features.  The same restrictions apply also to the use of
  608.  
  609.  
  610.                                      - 10 -
  611.  
  612.  
  613.         function   pointers  for  C/C++  and  function  names  as  formal
  614.         parameters in FORTRAN which cannot be  resolved  for  call  graph
  615.         generation.
  616.  
  617.         Several  useful  informations  and  software  metrics  about  the
  618.         processed source code and the included  files  can  be  generated
  619.         like
  620.  
  621.         -    file size and comment size in bytes for every file,
  622.         -    number of source code lines for every file,
  623.         -    number of included files for every source file,
  624.         -    total  effective number of scanned bytes and lines for every
  625.              source file and its included files,  if files  are  included
  626.              multiple times, this will influence the calculations,
  627.         -    for every defined function the number of lines, the code and
  628.              comment  size  in bytes,  the number of bytes per line,  the
  629.              number of functions  called,  the  number  of  flow  control
  630.              statements (if,  else,  for,  while,  case,  default,  goto,
  631.              return,  exit),  the maximum brace nesting level and if  the
  632.              function is used only inside the file,
  633.         -    for  every  defined  structure/union  the  total  number  of
  634.              elements and the number of  elements  which  are  themselves
  635.              structures/unions,
  636.         -    file function or data type reference list for every file,
  637.         -    total  number of displayed,  defined,  undefined or multiple
  638.              defined functions and data types,
  639.         -    location of all multiple defined functions and data types,
  640.         -    location of all overloaded C++ functions,
  641.         -    source file - include file  dependencies  for  every  source
  642.              file (MAKE-dependencies),
  643.         -    final statistical summary for all files,
  644.         -    cross  reference  of  every occurrence for every function or
  645.              data type,
  646.         -    parent/children relationship for  every  function  and  data
  647.              type,
  648.         -    critical  function  call path/structure nesting with deepest
  649.              non-recursive nesting level (unlimited tree depth),
  650.         -    C++ class inheritance graph,
  651.         -    FORTRAN subroutine CALLs,
  652.         -    FORTRAN COMMON blocks,
  653.         -    generation of description file  for  call/inheritance  graph
  654.              visualisation with the RATIONAL ROSE CASE tool
  655.              ...
  656.  
  657.         The resulting hierarchy structure chart is another representation
  658.         for  a  directed  call  graph.  A directed call graph consists of
  659.         nodes (functions or data types) and connections (call  relations)
  660.         between  these  nodes.  The number of nodes and connections which
  661.         are necessary to transform the hierarchy structure chart  into  a
  662.         directed  call  graph  will  also  be calculated as an additional
  663.         information about the system complexity.
  664.  
  665.  
  666.  
  667.  
  668.  
  669.  
  670.  
  671.                                      - 11 -
  672.  
  673.  
  674.         A large number of options to control the  program  execution  and
  675.         the  output  generation  are  available and can be defined on the
  676.         command line,  with interactive dialog windows (applies  only  to
  677.         Windows  versions),  by  command  files or by defining them in an
  678.         environment variable used by the program.
  679.  
  680.         CFT,  CST and the other SXT programs can be directly invoked from
  681.         inside  editors  or  integrated development environments like the
  682.         Borland C++ IDE.  Detailed examples for the integration  together
  683.         with necessary macro or batch files are given.
  684.  
  685.  
  686.  
  687.  
  688.  
  689.  
  690.  
  691.  
  692.  
  693.  
  694.  
  695.  
  696.  
  697.  
  698.  
  699.  
  700.  
  701.  
  702.  
  703.  
  704.  
  705.  
  706.  
  707.  
  708.  
  709.  
  710.  
  711.  
  712.  
  713.  
  714.  
  715.  
  716.  
  717.  
  718.  
  719.  
  720.  
  721.  
  722.  
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.  
  731.  
  732.                                      - 12 -
  733.  
  734.  
  735.         3    LANGUAGE IMPLEMENTATIONS
  736.  
  737.         3.1  C-LANGUAGE IMPLEMENTATION AND C-PREPROCESSOR
  738.  
  739.         The  ISO/ANSI  C  language  standard  ISO/IEC 9899:1990 (E) resp.
  740.         X3.159-1989-ANSI C  as  described  in  several  books  about  the
  741.         C-language  (see references) was used as a development base.  The
  742.         reserved keywords being recognised  are  not  only  the  original
  743.         ISO/ANSI  C  keywords  but  were also taken from several compiler
  744.         implementations like Microsoft,  Borland or  GNU  and  their  own
  745.         special  language  extensions.  The  books  "The  C++ Programming
  746.         Language" and "The Annotated C++ Reference Manual" (ARM) together
  747.         with informations about the work of the ANSI C++ committee  X3J16
  748.         resp.  the  ISO/IEC working group SC22 WG21 were used for the C++
  749.         keywords.  Another major source was the  AT&T  C++  release  2.1.
  750.         Compiler   specific  extensions  especially  from  GNU  are  also
  751.         recognised.  Proposed extensions to C  and  C++  like  additional
  752.         keywords (e.g.  wchar_t,  bool, namespace, using, ...) and the so
  753.         called 'digraphs' will be supported if they are  introduced  into
  754.         the language standard.
  755.  
  756.         A  complete  list of all reserved keywords is show in appendix 2.
  757.         The large set of keywords may lead to  some  slight  problems  in
  758.         situations  where  a  keyword  is  not  used  as itself but as an
  759.         identifier name,  for example a C++ keyword used as an identifier
  760.         in C.
  761.  
  762.         During a normal file scan,  precompiler defines are, if possible,
  763.         handled as if a real precompiler would be present,  but this  can
  764.         cause  some  trouble  with '#if',  '#ifdef' and other precompiler
  765.         controls which are not evaluated.  Also the block nesting  level,
  766.         which will be monitored by the source code scanner, may not be at
  767.         level  0  at  the  end  of  the  file because of such precompiler
  768.         controls. To avoid such things,  a built-in C-preprocessor allows
  769.         the  complete  preprocessing of the source code and include files
  770.         for several compiler types as an additional option (-P).
  771.  
  772.         Preprocessing or not is a little bit controversial because it can
  773.         either result in a loss of information  if  macros  are  used  to
  774.         change the program behaviour and hide function calls, it can lead
  775.         to  errors during file scanning or it can change the function and
  776.         data type informations obtained  from  the  code  which  may  not
  777.         exactly correspond to the visible source code.  Preprocessing can
  778.         be an advantage or not, so the user has to decide whether he does
  779.         it or not (see options -P, -I, -E for more informations).
  780.  
  781.         The  preprocessor  handles  the  defines  for  Microsoft  C  5.1,
  782.         Microsoft  C/C++  7.0,  Microsoft  VC++  1.0 for Windows NT (Beta
  783.         Release June 1993), Turbo C++ 1.0,  Borland C++ 2.0,  Borland C++
  784.         3.1,  GNU-C  and  Intel 80960 C compiler iC960 3.0 and all memory
  785.         models (not necessary for GNU-C and I960)  or  CPU  architectures
  786.         for the Intel 80960 32 bit RISC processor (KA,  KB,  SA,  SB, MC,
  787.         CA).  Other compiler types can be customised with the -B and  the
  788.         -D options.  The default ISO/ANSI C predefined macros '__FILE__',
  789.         '__LINE__',    '__DATE__',    '__TIME__'   are   generated    for
  790.         preprocessing.   The   macro  '__STDC__'  is  NOT  defined  (some
  791.  
  792.  
  793.                                      - 13 -
  794.  
  795.  
  796.         compilers test with '#ifndef __STDC__'),  so  that  non  standard
  797.         ISO/ANSI C extensions in the processed code are allowed. Defining
  798.         '-D__STDC__=1'  forces  ISO/ANSI  C conforming output (if used by
  799.         the  scanned  source  code,  of  course!).  Additional  supported
  800.         precompiler  defines  are  '__TIMESTAMP__',  '__BASE_FILE__'  and
  801.         '__INCLUDE_LEVEL__'.   A  list  of  the  predefined  preprocessor
  802.         defines  for the supported compiler types is shown in appendix 1.
  803.         Features like the replacing of trigraphs and the  recognition  of
  804.         C++ comments '//...' are also treated by the preprocessor.
  805.  
  806.         The precompiler recognises several errors or possible sources for
  807.         problems like
  808.  
  809.         -    the use of undefined variables in precompiler controls,
  810.         -    misbalanced  '#if...'  control  block(s) including the exact
  811.              location (file, line) where the failing block started,
  812.         -    recursive called include files,
  813.         -    nested include files,
  814.         -    wrong number of macro arguments (missing ones or too many)
  815.  
  816.         and displays diagnostic messages with an exact description of the
  817.         error or warning reason and its location in the source file.
  818.  
  819.  
  820.         3.2  C++ LANGUGAE IMPLEMENTATION
  821.  
  822.         For the description of the related  C++  language  standards  and
  823.         other   literature   see   the   chapter  about  the  C  language
  824.         implementation.
  825.  
  826.         Although CFT and CST were initially not developed to process  C++
  827.         code  it  is  possible  to  do so.  In that case,  however,  some
  828.         restrictions and limitations should be considered.
  829.  
  830.         The recognition of C++ classes by  CST  is  limited  because  the
  831.         handling  of  the  internal  class structure items (variables and
  832.         functions) is too complex to fit in the CST program.  So  classes
  833.         are only referenced by name but their internal structure will not
  834.         be scanned and displayed. The C++ class inheritance relationships
  835.         are  recognised  and  shown  in  a  class hierarchy graph listing
  836.         (option -b).  Structures in C++ with function names as  structure
  837.         members  will  not  be  processed  correctly.  Templates  are not
  838.         supported and will not be recognised.
  839.  
  840.         Calling member functions will not be recognised correctly due  to
  841.         missing  class  name,  this leads also to an incomplete call tree
  842.         and a lot of warnings during  analysis.  The  use  of  overloaded
  843.         functions  with  equal  names  but  different  parameters  in C++
  844.         programs may lead to incorrect calling relationships.  A variable
  845.         initialization  with  parameters  will  be  misinterpreted  as  a
  846.         function call. A correct handling of these and other C++ features
  847.         requires a complete C++ source code analyser to keep track of the
  848.         class functions belong to and the different calling parameters.
  849.  
  850.  
  851.  
  852.  
  853.  
  854.                                      - 14 -
  855.  
  856.  
  857.         If precise informations about C++ code are needed, utilities like
  858.         'class hierarchy browsers' or 'class viewers',  which are usually
  859.         (or should be) part of C++ compiler environments,  should be used
  860.         instead.
  861.  
  862.         Because of the above described reasons, some care should be taken
  863.         if C++ code is processed and displayed.
  864.  
  865.  
  866.         3.3  DBASE SOURCE CODE
  867.  
  868.         DFT can process source code which is based on  the  DBASE  III/IV
  869.         programming language. This means that also source code written in
  870.         DBASE  derivatives  like  CLIPPER  (Summer '87) or FOXBASE can be
  871.         analysed.  The source code analyser tries to  be  as  correct  as
  872.         possible to build a reliable hierarchy tree. A function/procedure
  873.         declaration  is  recognised  by  the  FUNCTION  resp.   PROCEDURE
  874.         keyword. A function/procedure call is recognised by the following
  875.         statements:
  876.  
  877.              function()
  878.              CALL function
  879.              CALL function WITH parameters
  880.              DO function
  881.              DO function WITH parameters
  882.  
  883.         If  a  file  contains  no  function/procedure  declaration,   the
  884.         filename  itself  is taken as procedure name.  The recognition of
  885.         builtin functions/procedures can be ignored (see option -E).  All
  886.         tokens   are   assumed  case-insensitive  and  are  converted  to
  887.         upper-case characters. Include files (e.g.  with CLIPPER) are not
  888.         processed.
  889.  
  890.  
  891.         3.4  FORTRAN SOURCE CODE
  892.  
  893.         FFT can process source which is based on the FORTRAN 77 standard.
  894.         Each  FORTRAN  line  is  divided  into  fields  for  the required
  895.         information, each column represents a single character.
  896.  
  897.              COLUMN    FIELD
  898.                   1    comment indicator (C,c,*,!)
  899.                 1-5    label
  900.                   6    indicator for line continuation
  901.                7-72    statement field
  902.  
  903.         Continuation lines  are merged  before  they  are  analysed.  The
  904.         number  of  continuation lines is 19 by default and can be varied
  905.         between 0 and 99 (option -qn).  Inline comments in the  statement
  906.         field start with '!',  the text until end of line is ignored. The
  907.         standard  intrinsic  functions   and   additionally   VAX-FORTRAN
  908.         intrinsic  functions are recognised.  Hollerith constants are not
  909.         recognised and handled.  All tokens are assumed  case-insensitive
  910.         and  are  converted  to  upper-case  characters.  Blanks  are not
  911.         significant and are not handled,  they  will  be  removed  except
  912.         inside character strings. If option -I is set, INCLUDE statements
  913.  
  914.  
  915.                                      - 15 -
  916.  
  917.  
  918.         are  recognised    and  processed.  To handle this implementation
  919.         dependent feature,  two different types of include statements are
  920.         accepted:
  921.  
  922.         C FORTRAN-LIKE SYNTAX, INCLUDE STATEMENT STARTS IN COLUMN 7
  923.               INCLUDE 'FILENAME'           ! SINGLE QUOTATION MARKS
  924.               INCLUDE FILENAME             ! WITHOUT QUOTATION MARKS
  925.  
  926.         C C-LIKE SYNTAX, INCLUDE STATEMENT STARTS IN COLUMN 1 WITH #
  927.         #INCLUDE "FILENAME"                ! DOUBLE QUOTATION MARKS
  928.         #INCLUDE FILENAME                  ! WITHOUT QUOTATION MARKS
  929.  
  930.         The  resulting  function  call  graph may be incorrect due to the
  931.         ENTRY capability of FORTRAN which  allows  direct  jumps  into  a
  932.         function  or  subroutine  body.  This  may  result  in  incorrect
  933.         relationships  for  the  ENTRY  statement  and  the   surrounding
  934.         function/subroutine.  The  indirect  call  of functions which are
  935.         given as formal parameters to subroutines or  functions  are  not
  936.         referenced  correct.  Implicit  typing  for  function definitions
  937.         without return type will not be recognised,  the function will be
  938.         displayed without a return type.
  939.  
  940.  
  941.         3.5  LISP SOURCE CODE
  942.  
  943.         LFT  can process LISP and SCHEME source code.  The development of
  944.         LFT was mainly based on the GNU-EMACS LISP dialect as it is  used
  945.         in  the  GNU-EMACS macro extension language and its functionality
  946.         was tested mainly with these macro files.  LISP  functions/macros
  947.         are  recognised  by  the  DEFUN  and  DEFMACRO  keywords.  SCHEME
  948.         functions are recognised by the DEFINE keyword, SCHEME processing
  949.         is enabled by option -XSCHEME.  Unnamed functions  declared  with
  950.         the   LAMBDA   keyword   can  be  recognised  optionally  (option
  951.         -XLAMBDA).  Tokens  are  assumed  case-sensitive.   Comments  are
  952.         recognised for ';' until end-of-line and between '#|' and '|#' as
  953.         multi line comment blocks.
  954.  
  955.         The  source  code  analysis is performed in two passes: The first
  956.         pass detects function/macro  declarations  and  the  second  pass
  957.         analyses  the relationships.  Function calls via (funcall <fcn>),
  958.         (function  <fcn>),  (apply  <fcn>),   (mapc  <fcn>)  and  similar
  959.         constructs   may   not   be  correctly  evaluated  if  fcn  is  a
  960.         function-symbol (e.g.  given as a function parameter) and  not  a
  961.         valid  function  name.  System  builtin  functions/macros  can be
  962.         specified by option -E.
  963.  
  964.         LFT was designed to work with different types of LISP source code
  965.         (as there are XLISP,  CLOS,  GNU-EMACS LISP,  ...),  although the
  966.         large  number  of  dialects  may  lead  sometimes  to  unexpected
  967.         problems.
  968.  
  969.  
  970.  
  971.  
  972.  
  973.  
  974.  
  975.  
  976.                                      - 16 -
  977.  
  978.  
  979.         3.6  ASSEMBLER SOURCE CODE
  980.  
  981.         As an additional feature,  CFT  and  FFT  can  process  assembler
  982.         source  code for the Intel 80x86 processors (MASM 5.1,  TASM) and
  983.         for the Intel 80960 RISC processors (or any other "AT&T UNIX-like
  984.         assembler"  like  GNU)  to  get   information   about   assembler
  985.         procedures  and  functions being called from the assembler source
  986.         files. The assembler source code scanner also detects and handles
  987.         calls of include files. This feature is useful for mixed language
  988.         programming. The processing of assembler macros, however,  is not
  989.         supported, the preprocessing option (-P) works only with C source
  990.         code.  Assembler  source  files  are  recognised  by  their  file
  991.         extensions '.ASM' and '.S', there is no other way to force a file
  992.         being processed as an assembler file.
  993.  
  994.         The following naming convention is  used:  For  '.ASM'  assembler
  995.         files  (MASM,  TASM) all identifiers are treated case-insensitive
  996.         and will be transformed to lower (CFT)  resp.  upper  (FFT)  case
  997.         characters,  but identifiers in '.S' (GNU,  I960) assembler files
  998.         are  treated  case-sensitive.  This  means,   that  an  assembler
  999.         function 'func1' defined in an '.ASM' file can be called from the
  1000.         source by 'func1',  'FUNC1', 'Func1' or any other lower and upper
  1001.         case character combination.  If 'func1' is  defined  in  an  '.S'
  1002.         file,  the name must match exactly.  The first leading underscore
  1003.         of a function name will be removed to get exact  naming  matches.
  1004.         Type modifiers in C source code like 'cdecl' or 'pascal' will not
  1005.         be  considered.  Remember  these  conventions  when processing C,
  1006.         FORTRAN and assembler files.
  1007.  
  1008.         Assembler code statements (inline code) inside C source code will
  1009.         not be processed and will be skipped, because it is too difficult
  1010.         to handle the several kinds of syntax being used for this    like
  1011.         'asm  ...',  'asm "..."' or 'asm(...)' and the different keywords
  1012.         ('asm', '_asm', '__asm', '__asm__', ...) used by various compiler
  1013.         implementations.
  1014.  
  1015.  
  1016.  
  1017.  
  1018.  
  1019.  
  1020.  
  1021.  
  1022.  
  1023.  
  1024.  
  1025.  
  1026.  
  1027.  
  1028.  
  1029.  
  1030.  
  1031.  
  1032.  
  1033.  
  1034.  
  1035.  
  1036.  
  1037.                                      - 17 -
  1038.  
  1039.  
  1040.         5    DATABASE GENERATION
  1041.  
  1042.         One of the most important features  is  the  database  generation
  1043.         which  can  be enabled with the -G option.  It is performed after
  1044.         writing the output  file  to  save  all  informations  about  the
  1045.         processed  files  in  a  set  of  dBASE compatible database files
  1046.         (extension '.DBF') for later use.  These database  files  contain
  1047.         all necessary informations like function or data type names,  the
  1048.         location   where   they   are   defined,    their   caller/callee
  1049.         relationship,  all  scanned  files  with  statistic informations,
  1050.         include files and so on.  It was tried to store the  informations
  1051.         in the most compact and effective database structure to save disk
  1052.         space.  Note  that  if  the  contents  of  the  database files is
  1053.         manipulated by external tools like dBASE or something  else,  the
  1054.         internal  consistency  will  be corrupted and wrong or unexpected
  1055.         results will happen!
  1056.  
  1057.         The database can be used to recall informations,  for example  to
  1058.         find  out,  if  and  in  which  file and on which line a specific
  1059.         function or data type is defined. A previously generated database
  1060.         can be read into CFT and CST (option -g) to add new files  to  it
  1061.         and/or  to  produce  another  output  file with new configuration
  1062.         options,  for example with the reverse call tree or only  with  a
  1063.         special  selected  item  of  interest  to  be displayed.  Such an
  1064.         incremental database generation is also useful if large  projects
  1065.         can  be  divided  into  a  set of commonly used files and project
  1066.         specific files.  A good example for this is the GNU  C  compiler,
  1067.         which  consists  of a set of language independent files and three
  1068.         language dependent file sets  for  C,  C++  and  Objective-C.  To
  1069.         analyse  this software with CFT or CST,  the language independent
  1070.         part can be stored into a database which is later reused for  the
  1071.         language   dependent   parts   to   build  the  complete  set  of
  1072.         informations.
  1073.  
  1074.         The ability to retrieve informations about the sources  from  the
  1075.         database  is  quite useful in many cases.  Recalling informations
  1076.         from a database is much faster than processing  all  the  sources
  1077.         again to find a specific item of interest.  The documentation and
  1078.         maintenance of large software projects is much more effective and
  1079.         easier to do if the developer has a tool to navigate through  the
  1080.         source  code  and  that  helps  him  in  his comprehension of the
  1081.         program and its internal structure. It is also useful for reverse
  1082.         engineering of source code to get an  overview  of  the  internal
  1083.         program structure.  Together with user programmable editors it is
  1084.         possible to offer the user a source code browser with a hypertext
  1085.         like feeling by integrating database recalling functions into the
  1086.         editors.
  1087.  
  1088.         Two  utility  programs,   called  CFTN  and  CSTN  to,   retrieve
  1089.         informations from databases, are available with supporting macros
  1090.         for their integration into the BRIEF, QEDIT or MicroEMACS editor,
  1091.         which are described in another section later in this manual.
  1092.  
  1093.  
  1094.  
  1095.  
  1096.  
  1097.  
  1098.                                      - 18 -
  1099.  
  1100.  
  1101.         6    PROGRAM LIMITATIONS
  1102.  
  1103.         First  of all,  CFT and CST cannot replace a compiler or a syntax
  1104.         checker like 'LINT' to detect errors in  the  source  code.  This
  1105.         means  that  it  should  be  possible  to compile the source code
  1106.         without fatal errors before it is possible to analyse it with CFT
  1107.         and CST,  otherwise the processing results may be incorrect  (and
  1108.         may be the system crashes ...).
  1109.  
  1110.         However,  there  are  some  situations  where  CFT and CST can be
  1111.         useful to detect bugs and inconsistencies in the source code like
  1112.  
  1113.         -    multiple definitions of functions or data types,
  1114.         -    different function return types,
  1115.         -    implicit declared functions with no prototype,
  1116.         -    function definitions used as prototype,
  1117.         -    recursive,  nested,  hidden and frequent  calls  of  include
  1118.              files,
  1119.         -    unterminated strings or character constants,
  1120.         -    nested comments,
  1121.         -    unterminated comments at end of file,
  1122.         -    misbalanced braces,
  1123.         -    unexpected end-of-file characters inside files,
  1124.         -    illegal characters in the source code,
  1125.         -    wrong number of macro arguments,
  1126.         -    missing macro arguments,
  1127.         -    misbalanced '#if...' control blocks.
  1128.  
  1129.         These  code  checks  are  done  on  multiple  files  in  multiple
  1130.         directories so that inconsistencies between different  files  can
  1131.         be  found and displayed.  This is a capability which conventional
  1132.         compilers working only on a single file at a time cannot  provide
  1133.         and will miss therefore (maybe the linker will find some of these
  1134.         inconsistencies).
  1135.  
  1136.         Some  statistical  informations  about the source code may not be
  1137.         correct if  preprocessing  is  enabled  (-P).  This  affects  all
  1138.         options which do statistics like the -p or -s option. The size of
  1139.         the  'pure' source code may not be correct due to macro expansion
  1140.         or removing of unnecessary blanks.  However,  the  file  size  is
  1141.         always correct because it will be taken from the source file.
  1142.  
  1143.         Most  of  the  program  limitations  are  caused  by  the limited
  1144.         available memory.  This means that  the  more  conventional  main
  1145.         memory you have,  the better it is. The real mode versions of CFT
  1146.         and CST do not use expanded or extended memory, no virtual memory
  1147.         management or disk  file  swapping,  so  keep  your  conventional
  1148.         memory  free of memory consuming TSR programs and other utilities
  1149.         if you want to process a  large  number  of  files.  The  use  of
  1150.         operating  systems  like  MS-DOS  6.0 and/or memory managers like
  1151.         QEMM or 386MAX to get more free conventional memory may  help  to
  1152.         handle  big applications with a large number of files.  If memory
  1153.         problems still occur during processing,  there is an easy way  to
  1154.         break  the  memory limits: use the 32 bit protected mode versions
  1155.         of CFT and CST,  called CFT386 and  CST386.  These  programs  are
  1156.         running  in protected mode and so they have no memory limitations
  1157.  
  1158.  
  1159.                                      - 19 -
  1160.  
  1161.  
  1162.         and are faster than the real mode versions.  You can also use the
  1163.         Windows 3.1, Win32s, Windows-NT and OS/2 versions which have also
  1164.         no memory limitations.
  1165.  
  1166.         The  number  and  the  sizes  of  files to be processed is nearly
  1167.         unlimited with 2^14 files and 2^31  bytes  maximum  file  length.
  1168.         Each  file can have 2^16 lines.  The number of functions and data
  1169.         types being handled is limited to 2^14.  Note that  these  values
  1170.         are given for the real mode versions, the protected mode versions
  1171.         usually exceed them.  These limitations should be enough even for
  1172.         the biggest project that could be mentioned.
  1173.  
  1174.         The calling of nested include files is limited by the  number  of
  1175.         files  which can be opened simultaneously (operating system resp.
  1176.         compiler dependent).  The ISO/ANSI C  minimum  for  include  file
  1177.         nesting  levels  is  8,  this demand will be fulfilled by CFT and
  1178.         CST.
  1179.  
  1180.         The integrated C-preprocessor limits the size of expanded  macros
  1181.         to  6  Kbytes.  The  number  of  macros simultaneously defined is
  1182.         unlimited (ISO/ANSI: 1024) and only  affected  by  the  available
  1183.         memory.   The  number  of  macro  parameters  is  limited  to  31
  1184.         (ISO/ANSI: 31) and there are  up  to  31  significant  characters
  1185.         (ISO/ANSI:  31)  recognised.  The conditional compilation nesting
  1186.         levels of '#if...' control blocks is limited to 32 (ISO/ANSI: 8).
  1187.  
  1188.         The line length is unlimited (ISO/ANSI: logical  line  length  is
  1189.         509 characters).  The number of characters in a string (including
  1190.         '\0') is 2048 (ISO/ANSI: 509).  The  number  of  members  in  one
  1191.         structure/union  is  unlimited  (ISO/ANSI:  127),  the  number of
  1192.         structure/union nesting levels is unlimited (ISO/ANSI: 15).
  1193.  
  1194.         The recognition of identifiers like function and  variable  names
  1195.         follows  the  standard rules: an identifier consists of upper and
  1196.         lower case letters (A-Z,  a-z),  underscore (_) and digits (0-9),
  1197.         additionally  the  dollar  sign  ($)  will be accepted.  National
  1198.         character set extensions as  they  are  usual  for  languages  in
  1199.         european countries like Germany, Denmark or Sweden can be defined
  1200.         with option -J.
  1201.  
  1202.         C++  comments  '//...' are usually only recognised if option -C++
  1203.         is set.  However,  to accept the non-standard extension  of  some
  1204.         compilers which allow such comments also in C source code, option
  1205.         -// can be used therefore.  Nested C style comments '/*...*/' are
  1206.         not allowed and will always produce warnings.
  1207.  
  1208.         CFT and CST may produce  warnings  with  wrong  line  numbers  if
  1209.         preprocessing  is  enabled  (option -P) and if the warning occurs
  1210.         inside a comment.  The reason is that line number synchronisation
  1211.         with '#line ...' is only guaranteed for executable source but not
  1212.         for  comments.  In  such  a  situation  the source code should be
  1213.         processed without  -P  to  get  the  correct  line  number  (such
  1214.         warnings are usually related to unexpected characters).
  1215.  
  1216.  
  1217.  
  1218.  
  1219.  
  1220.                                      - 20 -
  1221.  
  1222.  
  1223.         The  calculation  depth  of  the  critical  function call path or
  1224.         structure nesting level  is  unlimited.  The  calculation  is  an
  1225.         extremely    recursive function and was successfully tested up to
  1226.         more than 100 nesting levels.  It is not known from which nesting
  1227.         level on stack overflow will happen.
  1228.  
  1229.         CFT  cannot recognise and reference a function if it is used with
  1230.         its pure name,  without parentheses.  This happens if a  function
  1231.         name  is  assigned  to  a  function pointer variable or used as a
  1232.         function pointer argument in a function call. Indirect calls to a
  1233.         function via a function pointer cannot  be  resolved.  A  similar
  1234.         case  with  FFT is the use of function names as formal parameters
  1235.         and their use within subroutines or functions.
  1236.  
  1237.         CFT will be confused in some rare cases by extensive type-casting
  1238.         operations like 'void __based(void) * __cdecl ...  ()'  and  will
  1239.         display  unexpected  messages.  A  function prototype declaration
  1240.         inside a function block ('function  given  scope')  will  not  be
  1241.         recognised by CFT.  In assembler source code, some definitions of
  1242.         local  variables  seem  to  look  like  a  function  or  a  label
  1243.         definition  and are treated by CFT like that although this may be
  1244.         wrong in some cases.  It is also not always possible to detect  a
  1245.         call  of a local label correctly.  CFT sometimes displays warning
  1246.         messages about 'return type mismatch' though this may be  correct
  1247.         in  that  special  case  because  the different types are earlier
  1248.         defined by a 'typedef' declaration. The reason is simply that CFT
  1249.         doesn't recognise these 'typedef's (but CST does!), it looks only
  1250.         for function names.
  1251.  
  1252.         An often requested feature for CST  is  the  integration  of  the
  1253.         calculation   of   structure/union   sizes   with   byte   offset
  1254.         informations for every structure/union member.  This  feature  is
  1255.         not  implemented  in CST although it would be possible to do this
  1256.         because all necessary informations are  present.  The  reason  is
  1257.         that  there  would  be  too  much  overhead  for CST to treat the
  1258.         various compiler implementations with their different basic  type
  1259.         sizes (sizeof(int),  sizeof(long double)) for different processor
  1260.         types (16 bit,  32 bit,  64 bit,  ...) and  data  type  alignment
  1261.         requirements  (by default and also controlled with #pragma's like
  1262.         'align' or 'pack').  It would be possible to do this for just one
  1263.         selected  compiler implementation or processor type but not for a
  1264.         great  number  of  them.   Especially  compilers   for   advanced
  1265.         architectures  like  RISC  processors  have very complicated type
  1266.         alignments rules depending on the data types,  alignment pragmas,
  1267.         compiler  switches,  type  sizes,  available  register number and
  1268.         register  sizes  and  resulting  structure/union/class  sizes  to
  1269.         generate  highly  optimised  code.   This  includes  usually  the
  1270.         insertion of 'fill' bytes inside a structure/union and  sometimes
  1271.         'padding  bytes' at the end of a structure/union to force aligned
  1272.         sizes on specific byte boundaries (For examples see the reference
  1273.         manual of the Intel 80960 C-Compiler iC960, release 3.0). Because
  1274.         of these reasons,  an integrated 'byte offset calculation' is not
  1275.         implemented in CST.  Instead,  you can generate a source file for
  1276.         selected  data  types  with  option  -O,   that  performs   these
  1277.  
  1278.  
  1279.  
  1280.  
  1281.                                      - 21 -
  1282.  
  1283.  
  1284.         calculations,  if  you  compile  the  generated  file with your C
  1285.         compiler. For further informations see the description for option
  1286.         -O.
  1287.  
  1288.         Option -z  in  combination  with  option  -I  produces  redundant
  1289.         results  with CFT,  CST and FFT if files with executable code (or
  1290.         something that can be interpreted as that,  e.g.  function calls,
  1291.         data  types  or  COMMON  blocks)  are  included directly inside a
  1292.         function or data type block. (Especially in FORTRAN this seems to
  1293.         be common practice to include COMMON  blocks  into  function  and
  1294.         subroutine  bodies.)  For  CFT and CST (but not for FFT) also the
  1295.         call tree references will be incomplete and therefore  incorrect.
  1296.         With option -P for CFT and CST everything works fine, because the
  1297.         preprocessor  works  more  precise  as  the simple file inclusion
  1298.         mechanism option -I uses.
  1299.  
  1300.         SUMMARY
  1301.  
  1302.         The above described limitations can lead in  some  situations  to
  1303.         misinterpretations  or loss of informations of the scanned source
  1304.         code. The only way to avoid these lacks would be the inclusion of
  1305.         parts of a 'real compiler' to handle the complete language syntax
  1306.         in any possible situation.  But this was not the  intention  when
  1307.         the  development  of  these  programs as 'little' and easy to use
  1308.         general purpose programming supporting tools  began.  Although  I
  1309.         hope  that  the  SXT  programs will in most cases be powerful and
  1310.         useful development and documentation tools!
  1311.  
  1312.  
  1313.  
  1314.  
  1315.  
  1316.  
  1317.  
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324.  
  1325.  
  1326.  
  1327.  
  1328.  
  1329.  
  1330.  
  1331.  
  1332.  
  1333.  
  1334.  
  1335.  
  1336.  
  1337.  
  1338.  
  1339.  
  1340.  
  1341.  
  1342.                                      - 22 -
  1343.  
  1344.  
  1345.         7    IMPROVING EXECUTION SPEED
  1346.  
  1347.         CFT and CST are disk storage based programs  because  the  source
  1348.         and  include  files,  the  intermediate  precompiler file and the
  1349.         output file must be read from and  written  to  hard  disk.  This
  1350.         means that the execution speed of CFT and CST depends at first on
  1351.         the  speed  of  the physical storage medium and not (only) on the
  1352.         speed of the CPU.  There are several ways to improve the  program
  1353.         performance:
  1354.  
  1355.         -    install a RAM-disk and
  1356.              a)   start  CFT  and CST from there so that the intermediate
  1357.                   file and the resulting output file will be stored there
  1358.                   (but don't forget to copy the output file to  the  hard
  1359.                   disk before power-off), or
  1360.              b)   use  the  -v  option  to  redirect only the precompiler
  1361.                   output file (scanner input file) to the  RAM-disk  from
  1362.                   anywhere  the  program is started (the RAM-disk must be
  1363.                   large enough to hold  the  largest  possible  temporary
  1364.                   file, otherwise a disk-write error will occur),
  1365.         -    use a hard disk cache program like SmartDrive,  HyperDisk or
  1366.              PC-Cache,
  1367.         -    use a faster hard disk,
  1368.         -    and finally, of course, use a faster and more powerful CPU.
  1369.  
  1370.         The most effective combination is option -v with  a  RAM-disk  as
  1371.         destination  path and hard disk caching together with a fast hard
  1372.         disk drive. If the disk cache is large enough to hold most of the
  1373.         frequently called include files, the execution speed is about 2.5
  1374.         to 3 times faster than without.  This is a  significant  speed-up
  1375.         especially  for  projects  with  a large number of files and many
  1376.         included files in each source file.
  1377.  
  1378.         During program execution with preprocessing (option -P),  most of
  1379.         the time will be consumed to preprocess the given input files and
  1380.         the related include files and to generate the preprocessor output
  1381.         file.  The scanning for functions (CFT) or data types (CST) takes
  1382.         only a small amount of time. The function/data type relations are
  1383.         computed while the output is generated and written to disk, there
  1384.         is no precomputing necessary.
  1385.  
  1386.         The function  for  critical  call  path/nesting  level  detection
  1387.         depends  only on the number of functions or structures and not on
  1388.         the call/declaration nesting complexity. The execution time grows
  1389.         linear with the number of items (functions/structures) to process
  1390.         and is very fast!
  1391.  
  1392.         Be aware of the fact that the processing of  a  large  number  of
  1393.         files  can  take  quite  a  long time (from several minutes up to
  1394.         hours on lower performance machines!),  especially if  option  -P
  1395.         for preprocessing is enabled.
  1396.  
  1397.         The  generation  of  the output file and writing to disk can also
  1398.         take some time if the number of items to display is large and the
  1399.         nesting structure is complex or if there is  no  cross  reference
  1400.         option  enabled  (see -x and -r for further information).  If the
  1401.  
  1402.  
  1403.                                      - 23 -
  1404.  
  1405.  
  1406.         number of items is very large,  one of the  most  time  consuming
  1407.         options is the function/data type file reference (option -z). The
  1408.         writing  and  reading  of  the database files (options -G and -g)
  1409.         takes also some  time  due  to  the  large  number  of  different
  1410.         informations.
  1411.  
  1412.         Don't  panic  if  there  seems  to be no disk access for a longer
  1413.         time,  the reason is  just  that  there  may  be  time  consuming
  1414.         computations  and  that the output will be buffered internally to
  1415.         reduce the number of disk accesses and  therefore  speed  up  the
  1416.         output!
  1417.  
  1418.         For  more  detailed informations about the program efficiency see
  1419.         appendix 4.
  1420.  
  1421.  
  1422.  
  1423.  
  1424.  
  1425.  
  1426.  
  1427.  
  1428.  
  1429.  
  1430.  
  1431.  
  1432.  
  1433.  
  1434.  
  1435.  
  1436.  
  1437.  
  1438.  
  1439.  
  1440.  
  1441.  
  1442.  
  1443.  
  1444.  
  1445.  
  1446.  
  1447.  
  1448.  
  1449.  
  1450.  
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456.  
  1457.  
  1458.  
  1459.  
  1460.  
  1461.  
  1462.  
  1463.  
  1464.                                      - 24 -
  1465.  
  1466.  
  1467.         8    COMMAND LINE SYNTAX DESCRIPTION
  1468.  
  1469.         This section gives a complete overview about all SXT options  and
  1470.         their  syntax.  It  gives  also  remarks  for their use and shows
  1471.         several examples with  detailed  descriptions.  The  options  are
  1472.         case-sensitive!  There  are  no differences between the real mode
  1473.         and the other versions  of  the  SXT  programs.  In  the  Windows
  1474.         versions,  all  options can be set interactive by menu selections
  1475.         and dialog windows.  For every  option  the  SXT  programs  which
  1476.         support it are listed in parentheses.
  1477.  
  1478.         This  section of the documentation should be read very careful by
  1479.         all users to get a complete overview about all the features which
  1480.         are provided.
  1481.  
  1482.         THE OPTIONS ARE LISTED IN LEXICOGRAPHICAL ORDER.
  1483.         NONE OF THE OPTIONS IS SET BY DEFAULT.
  1484.  
  1485.         SYNTAX:   CFT [options [$cmdfile]] <[+]file> <@filelist>
  1486.                   CST [options [$cmdfile]] <[+]file> <@filelist>
  1487.                   DFT [options [$cmdfile]] <[+]file> <@filelist>
  1488.                   FFT [options [$cmdfile]] <[+]file> <@filelist>
  1489.                   LFT [options [$cmdfile]] <[+]file> <@filelist>
  1490.  
  1491.  
  1492.         OPTIONS:       (valid for program)
  1493.  
  1494.         -Bsizes        (CFT, CST)
  1495.         Redefine the basic type sizes and pointer type sizes (all  values
  1496.         must  be declared in bytes) for conditional preprocessor controls
  1497.         with the 'sizeof()' keyword like '#if  sizeof(int)  ==  4'.  This
  1498.         option is only valid with the -P option.
  1499.  
  1500.         The required format for this option is
  1501.  
  1502.              -Bv,c,s,i,l,f,d,ld*data,code
  1503.                                |
  1504.              (delimiter between data and pointer sizes is '*')
  1505.  
  1506.         with  the  following types and their respective default data size
  1507.         values in bytes (the pointer type sizes are model dependent):
  1508.  
  1509.         v    :    void (sizeof(void) is usually 0, but for GNU-C it is 1)
  1510.         c    :    char (1 byte)
  1511.         s    :    short (by definition 2 bytes, hardware independent)
  1512.         i    :    integer (hardware dependent, 2 or 4 bytes)
  1513.         l    :    long (4 bytes)
  1514.         f    :    float (4 bytes, IEEE format)
  1515.         d    :    double (8 bytes, IEEE format)
  1516.         ld   :    long double (10  bytes,  IEEE  format,  some  compilers
  1517.                   assume  long  double == double (= 8 bytes),  some CPU's
  1518.                   and their compilers have special alignment requirements
  1519.                   like the Intel 80960,  where sizeof(long double) is  16
  1520.                   bytes  due  to  register and memory access requirements
  1521.                   and structure alignment)
  1522.  
  1523.  
  1524.  
  1525.                                      - 25 -
  1526.  
  1527.  
  1528.         data :    data pointer (type pointers, 2 or 4 bytes, memory model
  1529.                   dependent)
  1530.         code :    code pointer (function pointers,  2 or 4 bytes,  memory
  1531.                   model dependent)
  1532.  
  1533.         The  sizes  of  signed and unsigned types of the same basic types
  1534.         are considered equal, this means that, for example, the following
  1535.         expression is true:
  1536.  
  1537.              sizeof(unsigned int) == sizeof(signed int) == sizeof(int)
  1538.  
  1539.         The sizes of type pointers to data and function pointers to  code
  1540.         are  also  considered equal,  this means that,  for example,  the
  1541.         following expressions are true:
  1542.  
  1543.              sizeof(int *) == sizeof(float *)
  1544.              sizeof(int (*)()) == sizeof(float (*)())
  1545.  
  1546.         A 64 bit (8 bytes) integer type like 'long long int' or  'bigint'
  1547.         (or  something  else)  is  currently  not supported although some
  1548.         (co-)processors and their assemblers are able to handle  it  (see
  1549.         Intel  80960  assembler manual for examples).  Also the DEC Alpha
  1550.         processor with its 64 bit architecture should support this.
  1551.  
  1552.         If the -B option is not set,  the default values for the  various
  1553.         memory  models  and  compiler types (as they are known to me) are
  1554.         used,   the  assumed  target  hardware   has   an   Intel   80x86
  1555.         microprocessor.  Note that during preprocessing type modificators
  1556.         like "near" or "far" are not recognised.
  1557.  
  1558.         If the -B and the -T options are  not  set,  the  sizes  of  data
  1559.         pointers and code pointers are always considered equal:
  1560.  
  1561.              sizeof(int *) == sizeof(int (*)())      (= 4, large model)
  1562.  
  1563.         For   example,   -B0,1,2,2,4,4,8,10*4,4   would  be  the  correct
  1564.         declaration for MS-C  7.0,  large/huge  memory  model,  with  the
  1565.         values for data types (void = 0,  char = 1,  short = 2,  int = 2,
  1566.         long = 4, float = 4,  double = 8 and  long double = 10 bytes) and
  1567.         pointers  to  data  types  and  function  pointers  (all values 4
  1568.         bytes).  These values are set automatically by defining -TMSC70,L
  1569.         (or  -TMSC70,H) as compiler type and memory model description for
  1570.         preprocessing.
  1571.  
  1572.         -C++           (CFT, CST)
  1573.         Enable C++ source code processing.  This includes the handling of
  1574.         C++  comments  '//...',  the  recognition of C++ keywords and the
  1575.         definition of the macro name '__cplusplus' for preprocessing.  If
  1576.         a   supported   compiler  defines  additional  macro  names  like
  1577.         '__TCPLUSPLUS__' for Turbo-C they will  also  be  defined  before
  1578.         preprocessing.  Option  -C++  is strictly required to process C++
  1579.         code correct.
  1580.  
  1581.  
  1582.  
  1583.  
  1584.  
  1585.  
  1586.                                      - 26 -
  1587.  
  1588.  
  1589.         -CALL          (FFT)
  1590.         Recognise and display only subroutine 'CALL ...' statements in  a
  1591.         function  or  subroutine  body.  In some cases this option can be
  1592.         useful if the source code scanner gets confused by indexed  array
  1593.         accesses  which  might be misinterpreted as function calls.  With
  1594.         this option only the 'CALL ...' statements are detected.
  1595.  
  1596.         -COMMON        (FFT)
  1597.         Recognize and display COMMON  block  names.  The  block  name  is
  1598.         surrounded by '/' like /name/,  a blank COMMON block is named //.
  1599.         In the output file,  COMMON block names are handled like function
  1600.         names,  e.g.  the  call statistics says '# calls'.  Note that the
  1601.         BRIEF and MicroEMACS macros cannot handle block  names  correctly
  1602.         since they do not accept the '/' character.
  1603.  
  1604.         -C[s]          (CFT, CST, DFT, FFT, LFT)
  1605.         List  the  function/data  type contents for every processed file,
  1606.         's' sorts by line numbers (DEFAULT ORDER: lexicographical). There
  1607.         are additional informations possible with the option -s. A remark
  1608.         is given if none of the functions defined in  a  file  is  called
  1609.         from  functions  defined in other files (internal versus external
  1610.         linkage). Functions for which no external caller outside the file
  1611.         is found will be marked [INTERNAL], such functions are candidates
  1612.         for defining them as 'static'. Attention: Calling a function by a
  1613.         function pointer won't be noticed!  This information is useful to
  1614.         find  out  whether  the contents of a file is unnecessary for the
  1615.         project so that the file must not be linked.  This  option  gives
  1616.         useful  informations  about source code metrics for every defined
  1617.         function.
  1618.  
  1619.         -D[..]         (CFT, CST, DFT, FFT, LFT)
  1620.         Specifies macro name(s) (-Dname or -Dname1=name2)  or  file  with
  1621.         macro names (-D@namelist) of functions/data types which should be
  1622.         predefined and linked together,  also used as preprocessor define
  1623.         if the integrated preprocessor is called (-P).  The defined names
  1624.         are case sensitive and trigraph translation is performed on them.
  1625.         For preprocessing, the -D option has lower precedence than the -U
  1626.         option. That is, if the same name is used in both a -U option and
  1627.         a  -D option,  the name will be undefined regardless of the order
  1628.         of the options.
  1629.  
  1630.         The definition of a string as replacement for  a  macro  name  is
  1631.         different  on the command line and inside a macro definition file
  1632.         or command file (marked with  '$').  On  the  command  line,  the
  1633.         double  quotation  marks must be 'escaped' and the string must be
  1634.         quoted like '-DXYZ="\"123\""' (similar  to  C  strings)  to  work
  1635.         correctly,  the  reason  is  the  DOS  wildcard  expansion of the
  1636.         command line.  Inside a macro definition  or  command  file,  the
  1637.         double  quotation marks need not be 'escaped',  so the definition
  1638.         can be written like '-DXYZ="123"'.  This option cannot be used in
  1639.         environment  defines  if  the equal sign '=' is used because this
  1640.         produces a syntax error for DOS when trying to store a  'SET=...'
  1641.         command  with  a second equal sign in one line.  If a define item
  1642.         consists  of  two  words  see  the  notes  at  option  -S  for  a
  1643.         description.  Keep  these  differences  and exceptions in mind to
  1644.         avoid unexpected results using the -D option.
  1645.  
  1646.  
  1647.                                      - 27 -
  1648.  
  1649.  
  1650.  
  1651.         -Ename         (CFT, CST, FFT)
  1652.         Almost the same as -I, but the path for the include files will be
  1653.         taken from the  environment  variable  'name'.  Typing  -EINCLUDE
  1654.         would produce the same results as -I alone.
  1655.  
  1656.         -E[..]         (DFT, LFT)
  1657.         Specifies  name(s)  (-Ename)  or file with names (-E@namelist) of
  1658.         external or builtin functions. For LISP, this option is useful if
  1659.         GNU-Emacs Lisp source code is scanned to  reduce  the  number  of
  1660.         undefined  functions  listed  in  the  output  file.  A  list  of
  1661.         GNU-EMACS (version 18.59) builtin functions  is  given  with  the
  1662.         file  GNULISP.FCT.  For DBASE,  CLIPPER and FOXBASE,  this option
  1663.         prevents output of builtin functions/keywords.  An  example  file
  1664.         with DBASE functions/procedures is provided with DBASE.FCT.
  1665.  
  1666.         -F             (CFT, CST, DFT, FFT, LFT)
  1667.         Use  only  ASCII  characters for the tree chart output instead of
  1668.         the DEFAULT semigraphic characters.  This option is useful if the
  1669.         generated  output  file should be printed on a printer which does
  1670.         not support semigraphic characters like they are defined  in  the
  1671.         IBM character set. It can also be used to prepare the output file
  1672.         for  use  in a WINDOWS application like MicroEMACS if there is no
  1673.         font with semigraphics available.
  1674.  
  1675.         -G[name]       (CFT, CST, DFT, FFT, LFT)
  1676.         Generate a database with the complete set of  informations  about
  1677.         the processed sources.  The additional parameter 'name' (path and
  1678.         file name) is used as an unique base name for the set of database
  1679.         files (up to 6 significant characters), the DEFAULT NAME 'CXT' is
  1680.         used if no name is specified. If 'name' ends with a (back-)slash,
  1681.         it is used as a pathname. The generated database files (extension
  1682.         '.DBF') are dBASE compatible.  There  are  two  additional  files
  1683.         created, one with the command line options (extension '.CMD') and
  1684.         one  with a list of the source files (extension '.SRC') being use
  1685.         for database  generation.  They  can  be  used  as  command  line
  1686.         definition files with '$' (command list) and '@' (file list).
  1687.  
  1688.         As  a result of the database generation you will find files named
  1689.         'CXTxy.ext' (default name 'CXT') respectively 'namexy.ext'  (user
  1690.         defined 'name'), where 'x' will be 'F' for CFT or 'S' for CST and
  1691.         'y'  is  replaced  by  an  internally  used character to mark the
  1692.         different database files and their contents.
  1693.  
  1694.         -H[elp]        (CFT, CST, DFT, FFT, LFT)
  1695.         See option -?.
  1696.  
  1697.         -I[path]       (CFT, CST, FFT)
  1698.         This option enables the scanning of include files  declared  with
  1699.         '#include "..."' or '#include <...>' or with a similar syntax for
  1700.         FORTRAN.  The  required  path for the include files is taken from
  1701.         the INCLUDE environment variable (DEFAULT BEHAVIOUR)  or  can  be
  1702.         user  defined  by 'path'.  Paths defined with -I will be searched
  1703.         before any other paths taken from environment variables specified
  1704.         by -E or -P,  so care should be taken with that  option.  Include
  1705.         paths  can be given either absolute or relative.  A relative path
  1706.  
  1707.  
  1708.                                      - 28 -
  1709.  
  1710.  
  1711.         is always considered relative to the directory of the source file
  1712.         it is used with,  not to the directory the  analysis  is  started
  1713.         from  or the analysis program is located.  Specifying -I* ignores
  1714.         missing include files during preprocessing (-P). This is a 'quick
  1715.         and dirty' approach,  but can sometimes  be  useful,  if  include
  1716.         interrelations or locations are unknown. However, the results may
  1717.         not always be correct.
  1718.  
  1719.         Using  the  -I or -E option without -P allows the scanning of the
  1720.         source file and the included files without preprocessing. In that
  1721.         case an include file is handled as if  it  were  a  complete  new
  1722.         file,  this  can  lead to errors if a file inclusion is specified
  1723.         within a function or structure.  Also preprocessor controls  like
  1724.         '#if  ...'  are not evaluated and can lead to unexpected results.
  1725.         Remember this especially if you place  special  comment  sections
  1726.         enclosed in '#if 0 ... #endif' blocks.
  1727.  
  1728.         -Jcharset      (CFT, CST, DFT, FFT, LFT)
  1729.         Extend  the  DEFAULT  character for identifier recognition with a
  1730.         user defined character set  'charset'.  All  characters  must  be
  1731.         specified within one -J option.  The following default identifier
  1732.         character sets are used:
  1733.  
  1734.              C/C++     a-z A-Z 0-9 _$
  1735.              DBASE     a-z A-Z 0-9 _
  1736.              FORTRAN   a-z A-Z 0-9 _
  1737.                        a-z A-Z 0-9 _$                (with option -$)
  1738.              LISP      a-z A-Z 0-9 +-.*/<=>!?:$%_&~^
  1739.  
  1740.         This option allows the programmer to use national character  sets
  1741.         as they are common in Germany, Denmark, Sweden and other european
  1742.         countries.
  1743.  
  1744.         -L[L][+]       (CFT, CST, DFT, FFT, LFT)
  1745.         Redirect  the  screen  output  to a file,  called 'CFT.LOG' resp.
  1746.         'CST.LOG'.  If '+' is set,  the output is both written to  screen
  1747.         and  redirected  to  the log file so that the output messages can
  1748.         both be viewed as they appear and later  analysed.  Finally,  -LL
  1749.         resp.  -LL+  appends the output to an existing file,  this can be
  1750.         useful if CFT and CST run in batch jobs.
  1751.  
  1752.         -M             (CFT, CST, FFT)
  1753.         This option generates a source file/include file dependency table
  1754.         for every processed file.  This table shows the dependent include
  1755.         files  of  a  source file and can be used for a MAKE file.  It is
  1756.         also useful to check if the included files  are  taken  from  the
  1757.         correct  directories.  If a file is included more than once,  the
  1758.         number of inclusions will be displayed.
  1759.  
  1760.         -N             (CFT, CST, DFT, FFT, LFT)
  1761.         Disable the writing of an output file.  This option can be useful
  1762.         if,  for example, only a database (option -G) should be generated
  1763.         with CFT or CST and no output file is required.  In that case the
  1764.         sometimes  very  time consuming process of output file writing is
  1765.         skipped.  Note that for CST the writing of the byte  offset  file
  1766.         "CST_OFFS.C" will not be affected by this option.
  1767.  
  1768.  
  1769.                                      - 29 -
  1770.  
  1771.  
  1772.  
  1773.         -NOINTR        (FFT)
  1774.         Do  not  recognise and display INTRINSIC functions in output tree
  1775.         chart.  Only subroutines and functions defined in the source code
  1776.         are displayed.
  1777.  
  1778.         -O[..]         (CST)
  1779.         Specifies  name(s)  (-Oname)  or file with names (-O@namelist) of
  1780.         data types for which the  calculation  of  structure/union  sizes
  1781.         with  byte  offset informations for every data type member should
  1782.         be performed.  Additionally specifying -O+ sets a  flag  for  the
  1783.         recursive collection of sub-structures during expansion which are
  1784.         displayed  without  specifying  them by -O.  This means that if a
  1785.         structure/union consists of members which are also structures  or
  1786.         unions (and so on), it is not necessary to specify all these data
  1787.         type  names  with  -O to enable them for byte offset calculation.
  1788.         Instead,  you have to specify only the top most  data  type  with
  1789.         -Oname  and  additionally  -O+ to force CST to select all related
  1790.         sub-types for  displaying.  If  -O+  is  set  but  NO  names  are
  1791.         specified, ALL structures and unions will be used for byte offset
  1792.         calculations!
  1793.  
  1794.         As  the  result  of  this option,  CST generates a C source file,
  1795.         called 'CST_OFFS.C'.  This file needs some additional editing  to
  1796.         declare necessary include files,  data types,  defines or pragmas
  1797.         before it can be compiled with the C compiler for which the  file
  1798.         was generated (be sure to use the same includes!).  The resulting
  1799.         executable prints  for  every  structure/union  member  the  byte
  1800.         offset  relative to the beginning of the structure/union (decimal
  1801.         and hexadecimal) and the  size  of  each  member,  the  resulting
  1802.         structure/union    size   and   also   informations   whether   a
  1803.         structure/union member has been  aligned  (=  compiler  dependent
  1804.         insertion   of   fill   bytes  before  that  member)  or  if  the
  1805.         structure/union was padded with fill bytes at the end  of  it  to
  1806.         align the size to a specific length.
  1807.  
  1808.         To   get   these   informations  and  to  perform  the  necessary
  1809.         calculations therefore,  the source file 'CST_OFFS.C' can  become
  1810.         very large and makes use of the C macro programming capabilities,
  1811.         which   may  lead  in  some  rare  cases  to  errors  during  the
  1812.         compilation due to the internal limitations of some C compilers.
  1813.  
  1814.         The -O option is very useful if you  need  detailed  informations
  1815.         about structures/unions in case of error searching and debugging,
  1816.         especially for hardware debugging with an ICE.  It is also useful
  1817.         for finding out the differences  in  the  internal  layout  of  a
  1818.         structure/union  in  the  case  of  porting C source code between
  1819.         different  compilers  and/or  operating  systems   or   if   data
  1820.         structures  are  exchanged  between different hardware platforms,
  1821.         for example with  data  communication.  You  can  verify  if  the
  1822.         expected  structure/union  layout  and size is really produced by
  1823.         the target compiler.
  1824.  
  1825.  
  1826.  
  1827.  
  1828.  
  1829.  
  1830.                                      - 30 -
  1831.  
  1832.  
  1833.         -P[name]       (CFT, CST)
  1834.         Run the integrated C preprocessor before the file scan.  In  this
  1835.         case  the  include  path  is  taken  from the INCLUDE environment
  1836.         variable  (DEFAULT  BEHAVIOUR),  from  the  user  defined  'name'
  1837.         environment  and additional paths from -I and -E option are used.
  1838.         If special paths should be searched  before  the  default  paths,
  1839.         they  must  be  specified  by  the  -I path or the -E environment
  1840.         option and they must be placed on the command line before the  -P
  1841.         option to be processed first. The -D, -U preprocessor defines and
  1842.         -T  type  and  memory  model and -B size infos are also used,  if
  1843.         defined.  The path  for  the  preprocessor  output  file  can  be
  1844.         specified  by  the  -v  option,  otherwise  the  current  working
  1845.         directory will be used (DEFAULT BEHAVIOUR).  The comments in  the
  1846.         source  and  included  files  will  remain until -q is defined to
  1847.         remove them. The comments are used for statistics with option -p.
  1848.         If option -C++ is set, the macro '__cplusplus' will be predefined
  1849.         before  preprocessing  to  enable  C++  macros  and  C++  comment
  1850.         recognition.
  1851.  
  1852.         If you are using a compiler which is not supported by CFT and CST
  1853.         or  the build-in preprocessing doesn't satisfy your needs because
  1854.         the results seem to be different from your preprocessor,  you can
  1855.         preprocess  the  files you want to analyse with your own compiler
  1856.         preprocessor and use these preprocessed files as  input  for  CFT
  1857.         and CST.
  1858.  
  1859.         -R             (CFT, CST, DFT, FFT, LFT)
  1860.         By default,  CFT and CST generate the hierarchy tree chart of the
  1861.         called function/data type ("CALLER:CALLEE relation",  "WHO CALLES
  1862.         WHOM").  The  -R  option produces an inverted listing showing the
  1863.         callers/users of each function/data type. It generates the output
  1864.         as the function/data type hierarchy member  list  tree  chart  in
  1865.         reverse  order as a list of calling items of the referenced basic
  1866.         item ("CALLEE:CALLER relation",  "WHO IS CALLED BY  WHOM").  This
  1867.         option  is  useful  to  get  the relations between functions/data
  1868.         types and their callers/users.
  1869.  
  1870.         -RATIONAL      (CFT, CST, DFT, FFT, LFT)
  1871.         This option generates a so called 'Petal' file for Rational  Rose
  1872.         2.0  (Windows),  a CASE-tool supporting the Booch Object-Oriented
  1873.         Analysis and Design (OOAD) method.  The generated output file can
  1874.         be  imported by Rational Rose 2.0 to use the builtin capabilities
  1875.         for describing and visualizing Finite State Machines  (FSM),  but
  1876.         in  this  case  (mis-)used  to  graphically visualize the calling
  1877.         relationships of functions resp. data types.
  1878.  
  1879.         If you have Rational Rose 2.0,  you have to perform the following
  1880.         steps to get impressive results: Start Rational Rose and select a
  1881.         new  model ('File' - 'New') and import the generated file ('File'
  1882.         - 'Import...').  If successful,  a class diagram with  one  class
  1883.         symbol named 'CallGraph' appears. Click on that symbol and choose
  1884.         'Browse' - 'State Diagram'. In the state diagram select 'Tools' -
  1885.         'Layout' to start the layout optimization function. As the result
  1886.         the  graphical call tree of the source code analysis is displayed
  1887.         with each function/data type shown as a circle ('state') and  the
  1888.         call  relationship  shown  as  an  arrow ('transaction') from the
  1889.  
  1890.  
  1891.                                      - 31 -
  1892.  
  1893.  
  1894.         calling to the called item,  for classes from the  superclass  to
  1895.         the subclass. You can zoom into the diagram, print the results or
  1896.         incorporate  the  diagrams  into  your  program documentation via
  1897.         Clipboard, e.g. into MS-Word-for-Windows.
  1898.  
  1899.         This option is available for  all  SXT  programs.  The  generated
  1900.         files are named 'CFT.PTL',  'CST.PTL',  'DFT.PTL' and so on.  CST
  1901.         generates an additional file named 'CSTCLASS.PTL' describing  the
  1902.         class  inheritance  relationships.  The  -RATIONAL  option  is  a
  1903.         work-around for the missing graphical layout capabilities of  the
  1904.         SXT  programs  (which  some  users have requested in the past) by
  1905.         using an external program for doing the missing features.
  1906.  
  1907.         The -RATIONAL option was tested with the Beta Release of Rational
  1908.         Rose/C++ 2.0 (Windows).  Note that Rational Rose needs  even  for
  1909.         small  and medium sized projects some time to import the file and
  1910.         process the FSM layout.
  1911.  
  1912.         -S[..]         (CFT, CST, DFT, FFT, LFT)
  1913.         Specify  name  (-Sname)  or  file  with  names  (-S@namelist)  of
  1914.         functions/data types to search for and to dump if present,  names
  1915.         are case sensitive.  These items are listed first in  the  output
  1916.         tree chart file. By using -S on the command line, it is necessary
  1917.         to  surround  a  data  type  name that consists of two words with
  1918.         double quotation marks like "struct _iobuf" to  connect  the  two
  1919.         words.  This is not necessary inside a list file, but there every
  1920.         search name must be on a separate line.
  1921.  
  1922.         -Tn            (FFT)
  1923.         Set the tabulator expansion size to 'n' (DEFAULT: 8 characters).
  1924.  
  1925.         -Ttype,m       (CFT, CST)
  1926.         Use this  option  to  set  the  compiler  type  for  source  code
  1927.         preprocessing to one of the following types:
  1928.  
  1929.              MSC51     Microsoft C 5.1
  1930.              MSC70     Microsoft C/C++ 7.0
  1931.              MSVC15    Microsoft Visual C++ 1.5
  1932.              MSVCWNT   Microsoft Visual C++ 1.0 for Windows NT
  1933.              TC10      Borland Turbo C++ 1.0
  1934.              BC20      Borland C++ 2.0
  1935.              BC31      Borland C++ 3.1
  1936.              BC10OS2   Borland C++ 1.0 for OS/2
  1937.              GNU       GNU-C
  1938.              I960      Intel 80960 iC960 3.0
  1939.  
  1940.         The  supported  memory  models  are T(iny) (valid only for MSC70,
  1941.         MSVC15, TC10, BC20, BC31), S(mall), M(edium), C(ompact), L(arge),
  1942.         H(uge),  'L' is assumed as default if no model is  specified.  MS
  1943.         VC++ for Windows NT,  Borland C++ for OS/2, GNU-C and Intel iC960
  1944.         do not need a memory model because they  compile  really  32  bit
  1945.         code.  The  Intel  iC960  compiler requires the definition of the
  1946.         80960 RISC processor architecture which is one of KA, KB, SA, SB,
  1947.         MC, CA (default is KB).
  1948.  
  1949.  
  1950.  
  1951.  
  1952.                                      - 32 -
  1953.  
  1954.  
  1955.         This option causes several compiler dependent preprocessor macros
  1956.         (if they  were  known  to  me,  however)  to  be  defined  before
  1957.         preprocessing  starts.  This  option can only be used with the -P
  1958.         option, otherwise it has no effect.
  1959.  
  1960.         If your compiler is not supported,  you can perform the following
  1961.         steps: Find out which preprocessor defines are necessary (manual,
  1962.         help  file)  and  declare  them  with  option  -D,  then declare,
  1963.         depending on the selected memory model or processor architecture,
  1964.         the type sizes with option -B.
  1965.  
  1966.         -U[..]         (CFT, CST)
  1967.         Specifies  a  predefined  macro  name  (-Dname)  or   file   with
  1968.         predefined   macro   names  (-U@namelist)  to  be  undefined  for
  1969.         preprocessing.  Note that  the  default  predefined  macro  names
  1970.         '__FILE__',   '__LINE__',   '__DATE__',   '__TIME__'   cannot  be
  1971.         undefined.  All other predefined names for the  various  compiler
  1972.         types  can  be undefined.  Like for -D,  the names are considered
  1973.         case-sensitive, but trigraph translation is not performed because
  1974.         the internal representation cannot contain trigraphs.
  1975.  
  1976.         -V             (CFT)
  1977.         List prototyped functions which are neither  called  nor  defined
  1978.         (option -a and -u). This option is useful to find unused function
  1979.         prototypes which could be removed from the source code.
  1980.  
  1981.         -Wlevel        (CFT, CST, DFT, FFT, LFT)
  1982.         Set  error  and  warning  message  level.  Higher  warning levels
  1983.         include lower ones.  The DEFAULT  level  is  always  the  highest
  1984.         supported warning level, possible levels are:
  1985.  
  1986.         0 :  all   error  and  warning  messages  are  suppressed  except
  1987.              absolutely catastrophic fatal errors,
  1988.         1 :  display serious errors or warnings,
  1989.         2 :  includes level 1 plus additional errors and warnings,
  1990.         3 :  includes level 2 plus errors/warnings/remarks,
  1991.         4 :  includes level  3  plus  warnings  about  implicit  declared
  1992.              functions and lacks of type or storage class.
  1993.  
  1994.         The following levels affect only preprocessing (CFT and CST):
  1995.  
  1996.         5 :  includes   level   4   plus   warnings   and  errors  during
  1997.              preprocessing  (non-fatal   errors   and   warnings   during
  1998.              preprocessing  are otherwise not displayed,  preprocessor is
  1999.              running in 'silent mode'),
  2000.         6 :  includes  level  5  plus  remarks/slight   warnings   during
  2001.              preprocessing.
  2002.  
  2003.         The output format for messages during file scan is
  2004.  
  2005.              file name(line): error: description
  2006.              file name(line): warning: description
  2007.  
  2008.  
  2009.  
  2010.  
  2011.  
  2012.  
  2013.                                      - 33 -
  2014.  
  2015.  
  2016.         and during preprocessing (warning levels 5 and 6)
  2017.  
  2018.              preprocessor: file name(line): error: description
  2019.                   source line
  2020.              preprocessor: file name(line): warning: description
  2021.                   source line
  2022.  
  2023.         -X             (CFT, CST, DFT, FFT, LFT)
  2024.         Assume  a  UNIX-style  text  file:  no CR,  only LF.  The DEFAULT
  2025.         ASSUMPTION is  a  DOS-style  text  file  with  CR+LF.  Any  other
  2026.         combination like CR in UNIX-files,  CR without following LF or LF
  2027.         without preceding CR in DOS-files will cause a  warning  message.
  2028.         This  option  is  useful  to  detect  possible  conversion errors
  2029.         between  different  operating   systems   or   incorrect   editor
  2030.         configuration settings.
  2031.  
  2032.         -XLAMBDA       (LFT)
  2033.         Recognise  the  LISP  resp.  SCHEME  keyword 'lambda' for unnamed
  2034.         function declarations.  By DEFAULT,  'lambda'  is  treated  as  a
  2035.         simple identifier.
  2036.  
  2037.         -XSCHEME       (LFT)
  2038.         Assume  SCHEME source code instead of LISP source code (DEFAULT).
  2039.         This means that functions are recognised by the  'define'  SCHEME
  2040.         keyword instead of the 'defun' resp. 'defmacro' LISP keywords.
  2041.  
  2042.         -Y             (CFT, CST, DFT, FFT, LFT)
  2043.         Ignore  CR+LF  checks.  This option disables all checks which are
  2044.         done for unexpected CR+LF combinations in DOS or UNIX  files.  If
  2045.         option -Y is set,  option -X will be ignored.  This option can be
  2046.         useful if there would be too many messages concerning that  error
  2047.         or if this message would be of no interest for the user.
  2048.  
  2049.         -Z[s]          (CFT, CST, DFT, FFT, LFT)
  2050.         Display every caller and member for each function/data type,  's'
  2051.         sorts by the number of calls  (DEFAULT  ORDER:  lexicographical),
  2052.         this  is  an  extension  of the -c option.  This option shows the
  2053.         relations in the following form:
  2054.  
  2055.              List of parent functions/data types:
  2056.              1. caller (reference #) <# of calls from>
  2057.              ...
  2058.              n. caller ...
  2059.         function/data type (reference #) <# of calls from parents,  #  of
  2060.         calls to children>
  2061.              List of child functions/data types:
  2062.              1. called member (reference #) <# of calls to>
  2063.              ...
  2064.              m. called member ...
  2065.  
  2066.         This  compact  form lists all callers and members with the number
  2067.         of their calls, recursions are detected and displayed.
  2068.  
  2069.  
  2070.  
  2071.  
  2072.  
  2073.  
  2074.                                      - 34 -
  2075.  
  2076.  
  2077.         -a             (CFT, CST, DFT, FFT, LFT)
  2078.         List  every  function/data  type,   also  previously   referenced
  2079.         functions/data  types.  This  generates  a complete list of every
  2080.         function/data type in lexicographical order  with  references  to
  2081.         their first location.
  2082.  
  2083.         -b             (CST)
  2084.         Display  the  C++  class  inheritance relationships.  This option
  2085.         generates two listings.  The first one displays the complete  C++
  2086.         class  hierarchy  graph(s).  The  second one shows for each class
  2087.         first the superclasses from which  the  class  inherits  and  the
  2088.         access restrictions (public,  protected, virtual, ...) and second
  2089.         the subclasses which inherit from  the  given  class,  also  with
  2090.         access  restrictions.  This  option  is useful to find out things
  2091.         like the class dependencies or multiple inheritance.
  2092.  
  2093.         -cmdline       (CFT, CST, DFT, FFT, LFT)
  2094.         Print the command line options at the  beginning  of  the  output
  2095.         file  as  a remark for the generation rules for that output file.
  2096.         All options and files specified  on  the  command  line,  in  the
  2097.         environment variable,  the commandlist and the filelist files are
  2098.         listed.
  2099.  
  2100.         -c[s]          (CFT, CST, DFT, FFT, LFT)
  2101.         Display the number of calls to each function/data type, 's' sorts
  2102.         by the number of calls (DEFAULT ORDER:  lexicographical).  Useful
  2103.         to  find  out  which  functions/data  types are never called/used
  2104.         (maybe unnecessary and deletable) and which  ones  are  the  most
  2105.         frequently  called/used (together with profiler results a subject
  2106.         for  further  optimization  efforts).   For  FFT  see  also   the
  2107.         description for option -CALL.
  2108.  
  2109.         -defmacro      (LFT)
  2110.         Recognise the 'defmacro' keyword in SCHEME source code.
  2111.  
  2112.         -dn            (CFT, CST, DFT, FFT, LFT)
  2113.         Set the maximum function/structure/union nesting level for output
  2114.         generation  to  'n' (DEFAULT: maximum value n = 999).  This means
  2115.         that the request for displaying a deeper level will  be  rejected
  2116.         and the output tree chart will be truncated at the given level.
  2117.  
  2118.         -e[char]       (CFT, CST, DFT, FFT, LFT)
  2119.         Generate  formatted ASCII text files with function/data type list
  2120.         and file list.  All entries are separated by the optional  'char'
  2121.         character,  if 'char ' is not defined, the tabulator character is
  2122.         used as DEFAULT SEPARATOR.  If spaces are  wanted  as  separating
  2123.         characters,  you have to write -e" ".  Such prepared files can be
  2124.         used directly as input to other  programs  like  word  processors
  2125.         (e.g.  MS-WORD  for  WINDOWS)  or  spreadsheet  calculators (e.g.
  2126.         MS-EXCEL), for example for documentation purposes.  The following
  2127.         files are created:
  2128.  
  2129.  
  2130.  
  2131.  
  2132.  
  2133.  
  2134.  
  2135.                                      - 35 -
  2136.  
  2137.  
  2138.         CFTITEMS.TXT:
  2139.         Contents: function name,  return type, file name, line #, total #
  2140.         of function bytes,  # of function comment bytes,  #  of  function
  2141.         lines, # of control statements, # of brace levels
  2142.  
  2143.         CSTITEMS.TXT:
  2144.         Contents: data type name, file name line #
  2145.  
  2146.         CFTFILES.TXT and CSTFILES.TXT:
  2147.         Contents: file name, # of lines, file size in bytes, # of comment
  2148.         bytes, # of functions/data types
  2149.  
  2150.         -f             (CFT, CST, DFT, FFT, LFT)
  2151.         Generate   an   output   list  in  short  form,   only  with  the
  2152.         function/data type names,  no further description of the internal
  2153.         function/data type elements.
  2154.  
  2155.         -g[name]       (CFT, CST, DFT, FFT, LFT)
  2156.         Read  a  previously  generated  database  (see  option  -G).  The
  2157.         additional parameter 'name' (path and file name) is  used  as  an
  2158.         unique  base  name  for  the  set  of  database  files  (up  to 6
  2159.         significant characters),  the DEFAULT NAME 'CXT' is  used  if  no
  2160.         name is specified. If 'name' ends with a (back-)slash, it is used
  2161.         as  a  pathname.  Every source file will be tested for changes of
  2162.         file creation time and file size and a warning  message  will  be
  2163.         given to inform the user.
  2164.  
  2165.         -h[elp]        (CFT, CST, DFT, FFT, LFT)
  2166.         See option -?.
  2167.  
  2168.         -iname         (CFT, DFT, FFT, LFT)
  2169.         Ignore  function member 'name' in output tree chart.  It will not
  2170.         be displayed and will be skipped instead if found as  a  function
  2171.         member.  This option can be useful if, for example, functions are
  2172.         used only for test purposes and are of no  further  interest  for
  2173.         the  user  and should be ignored in the output tree chart.  It is
  2174.         also possible to specifiy library functions so  that  the  output
  2175.         tree chart contains only user defined functions.
  2176.  
  2177.         -l             (CFT, DFT, FFT, LFT)
  2178.         List  a  function only once in case of repeated consecutive calls
  2179.         (DEFAULT: display every occurrence). If a function is called more
  2180.         than one time  inside  a  function  without  any  other  call  in
  2181.         between,  there  will be only one reference of that function call
  2182.         in the output tree chart.  This option results in shorter  output
  2183.         files.
  2184.  
  2185.         -mtype         (CST)
  2186.         Start  the  data  type tree chart with data type 'type' (-mtype).
  2187.         If -m+ is specified,  the output starts  with  the  topmost  data
  2188.         type,  this is the data type which is in the highest level of the
  2189.         hierarchy tree chart.  The default output is  in  lexicographical
  2190.         order  of  the  displayed  data  types.   Useful  if  a  selected
  2191.         structure/union should be  displayed  at  the  beginning  of  the
  2192.         output file.
  2193.  
  2194.  
  2195.  
  2196.                                      - 36 -
  2197.  
  2198.  
  2199.         -m[name]       (CFT, FFT)
  2200.         -mname         (DFT, LFT)
  2201.         Start the function tree chart dump with function 'main' (CFT -m),
  2202.         'PROGRAM' (FFT -m) or 'name' (-mname), name is case sensitive. If
  2203.         -m+  is  specified,  the output starts with the topmost function,
  2204.         this is the function  which  is  in  the  highest  level  of  the
  2205.         hierarchy tree chart.  If this option is not set,  the default is
  2206.         lexicographical order of the displayed functions.
  2207.  
  2208.         Usually,  the complete function tree chart should start with  the
  2209.         'main'  function  so  that every subfunction is a (sub-)member of
  2210.         'main'.  This option is useful for windows programs to start  the
  2211.         output with the initial 'WinMain' function (-mWinMain) instead of
  2212.         'main'.  It can also be used to start the output with the initial
  2213.         assembler start-up code being executed before the 'main'-function
  2214.         is called.
  2215.  
  2216.         -n[a]          (CFT, CST, DFT, FFT, LFT)
  2217.         Display the most critical function call path respectively display
  2218.         the data structure/union with  the  maximum  nesting  level.  The
  2219.         modificator  'a' is used to display every function/structure with
  2220.         its users/callers (DEFAULT: display only deepest call path). This
  2221.         option  helps  to  determine  the  complexity  of  the   function
  2222.         call/data  structure  hierarchy and finds recursions over several
  2223.         call/nesting levels.  Note that for functions  the  maximum  call
  2224.         path  being  displayed  is  the  result of the static source code
  2225.         analysis.  During program execution the call  path  can  be  even
  2226.         deeper  if functions are called indirectly with function pointers
  2227.         or similar mechanisms.
  2228.  
  2229.         -noundef       (CFT, DFT, FFT, LFT)
  2230.         Ignore undefined items (functions,  subroutines) in  output  tree
  2231.         chart.  Display  only  those  which  are  really  defined  in the
  2232.         analysed source code.
  2233.  
  2234.         -ofile         (CFT, CST, DFT, FFT, LFT)
  2235.         Write the generated analysis  results  to  file  'file'.  DEFAULT
  2236.         BEHAVIOUR: The file names are 'CFT.LST' for CFT and 'CST.LST' for
  2237.         CST.  Possible  overwriting  of  an existing output file with the
  2238.         same name other  than  the  default  one  will  be  detected  and
  2239.         prompted  for user reconfirming.  The resulting output file is an
  2240.         ASCII text file  with  no  formatting  characters  which  can  be
  2241.         printed with every printer,  viewed and/or edited with every text
  2242.         editor and taken as input to word  processors,  for  example  for
  2243.         documentation purposes.
  2244.  
  2245.         -p             (CFT, CST, DFT, FFT, LFT)
  2246.         Calculate  the  program  code/file  size ratio for every file and
  2247.         make a final summary.  This option gives a short  overview  about
  2248.         the 'real' file contents versus complexity. The computed value is
  2249.         in  the  range from 0.000 (only comment,  no code) to 1.000 (only
  2250.         code, no comment). Used together with -P,  the results may not be
  2251.         absolutely correct because of the macro expanding and removing of
  2252.         parts  of  the  source  code  by  '#if...'  control  blocks.   If
  2253.  
  2254.  
  2255.  
  2256.  
  2257.                                      - 37 -
  2258.  
  2259.  
  2260.         preprocessing -P is enabled, comment byte count in included files
  2261.         will not be performed. If option -q is set, -p will not calculate
  2262.         values related with comments.
  2263.  
  2264.         -q             (CFT, CST)
  2265.         Remove comments from preprocessed files, default is don't remove.
  2266.         This option is only valid with option -P,  it also affects the -p
  2267.         option because counting comments is not possible and calculations
  2268.         on them cannot be done.
  2269.  
  2270.         -qn            (FFT)
  2271.         Set  the number of continuation lines to 'n' (DEFAULT: 19 lines).
  2272.         The number must be in the range from 0 to 99.
  2273.  
  2274.         -r             (CFT, CST, DFT, FFT, LFT)
  2275.         This is almost the same as option  -x,  but  an  additional  file
  2276.         reference  with  the  file  name  and  the  line  number  of  the
  2277.         declaration will be given (includes -x).
  2278.  
  2279.         The -r or the -x option is STRICTLY  RECOMMENDED  and  should  be
  2280.         used as a default option, because without it, every function/data
  2281.         type  will  be  completely redisplayed,  including the underlying
  2282.         subtree of functions or data types,  whenever it  occurs  in  the
  2283.         output  tree  chart  and  so  the resulting output file will grow
  2284.         immense,  up to several megabytes,  if there is enough disk space
  2285.         to write the output file.
  2286.  
  2287.         -s             (CFT, CST, DFT, FFT, LFT)
  2288.         Used with -C,  this option gives additional informations. For CFT
  2289.         for every function: the number of lines for  the  function  body,
  2290.         the  maximum  brace levels,  the number of bytes for the function
  2291.         body and the number of comment bytes inside  the  function  body.
  2292.         The  average  values  for  every  source  file  are  computed and
  2293.         displayed.  For CST for every data type: number of type elements,
  2294.         number of subelements (nested structures/unions).
  2295.  
  2296.         -time          (CFT, CST, DFT, FFT, LFT)
  2297.         Print  runtime  informations  about the times consumed for source
  2298.         analysis,  preprocessing,  output  dump,   database  reading  and
  2299.         writing and for other miscellaneous jobs plus the total time. The
  2300.         results are given in the format MINUTE:SECOND.MILLISECOND.
  2301.  
  2302.         -u             (CFT, DFT, FFT, LFT)
  2303.         List  undefined  functions.  These functions are probably library
  2304.         functions,  defined in other files which have not been scanned or
  2305.         are unresolved externals found by the linker.
  2306.  
  2307.         -vpath         (CFT, CST, FFT)
  2308.         Set a specific path for the intermediate precompiler output file.
  2309.         'path'  can  be a pathname or a drive letter with pathname,  e.g.
  2310.         'c:\tmp' or 'g:\' (not 'g:' without '\', this is an error).  This
  2311.         option   is   useful   to  speed  up  execution  speed  when  the
  2312.         intermediate file can be stored on a RAM-disk so that file access
  2313.         to the precompiled file is much  faster  than  on  a  hard  disk.
  2314.         Environment  variables  like  'TMP' or 'TEMP' to set the path for
  2315.         temporary files are not evaluated.
  2316.  
  2317.  
  2318.                                      - 38 -
  2319.  
  2320.  
  2321.  
  2322.         -x             (CFT, CST, DFT, FFT, LFT)
  2323.         Cross reference in case of multiple use.  Every function and data
  2324.         type   will  be  given  a  unique  reference  number  which  will
  2325.         furthermore be used as an identifying reference  number  for  the
  2326.         function  or data type if it is again displayed.  See also option
  2327.         -r for further descriptions.
  2328.  
  2329.         -y             (CFT, CST, DFT, FFT, LFT)
  2330.         Display cross link list of files which  contain  referencing  and
  2331.         referenced  functions/data  types  of  functions/data  types of a
  2332.         specific file.  This option shows the relations in the  following
  2333.         form:
  2334.  
  2335.              1. referencing file
  2336.              ...
  2337.              n. referencing file
  2338.         file
  2339.              1. referenced file
  2340.              ...
  2341.              m. referenced file
  2342.  
  2343.         This  option  is  useful  if  you  want  to  find  out  the  file
  2344.         relationships.  This information can be used to isolate  specific
  2345.         files from a project,  e.g.  library files.  It is also useful if
  2346.         you want to separate a function and  want  to  know  which  other
  2347.         files are needed because they contain called functions.
  2348.  
  2349.         -z             (CFT, CST, DFT, FFT, LFT)
  2350.         Generate  a  function/data  type call cross reference table.  For
  2351.         every function/data type the location of  its  definition  (file,
  2352.         line)  and  a  complete  list of its calls/references,  sorted by
  2353.         files and line numbers is given in the following form:
  2354.  
  2355.         1. function/data type (reference #) [file #], line #
  2356.              [file #]: line #, ...
  2357.              ...
  2358.  
  2359.         2. ...
  2360.              ...
  2361.  
  2362.         The functions/data types are displayed in lexicographical  order.
  2363.         At the end of the section is the cross reference file list.
  2364.  
  2365.         -$             (FFT)
  2366.         Recognise $ as identifier character, not as delimiter. Useful for
  2367.         source code written for VAX (VMS)- or IBM (MVS)-Fortran.
  2368.  
  2369.         -//            (CFT, CST)
  2370.         Accept C++ comments '//...' in C source code.  This option can be
  2371.         used to ensure compatibility with  C  compilers  which  can  also
  2372.         recognise  C++  comments within C source code (like Microsoft and
  2373.         Borland).
  2374.  
  2375.  
  2376.  
  2377.  
  2378.  
  2379.                                      - 39 -
  2380.  
  2381.  
  2382.         -?             (CFT, CST, DFT, FFT, LFT)
  2383.         Shows the command line syntax and gives  a  short,  but  complete
  2384.         help information about the accepted commands and their syntax.
  2385.  
  2386.  
  2387.         COMMAND LINE FILES
  2388.  
  2389.         cmdfile        (CFT, CST, DFT, FFT, LFT)
  2390.         Specifies  a  file  with (additional) command line options.  This
  2391.         might be useful if the command line would be too long because  of
  2392.         the  number  of  options and files declared or if you are usually
  2393.         using the same options which can then  be  stored  in  a  command
  2394.         file.  The  initial  '$'-character  is required to mark a command
  2395.         file.
  2396.  
  2397.         filelist       (CFT, CST, DFT, FFT, LFT)
  2398.         A file with a list of source file(s) to be  processed,  wildcards
  2399.         are  accepted.  The  list file should have every file on a single
  2400.         line.  The rules for files containing  assembler  code  and  path
  2401.         translation  are  described  above.  The initial '@'-character is
  2402.         required to mark a filelist file.  The '+' sign for  subdirectory
  2403.         processing is also possible inside the filelist file.
  2404.  
  2405.         [+]file        (CFT, CST, DFT, FFT, LFT)
  2406.         The name of a source file to be processed. More than one file can
  2407.         be specified on the command line.  The default assumption for the
  2408.         given files is that they contain C source code.  Assembler source
  2409.         files  are  only  recognised  by the file extension '.ASM' (80x86
  2410.         MASM/TASM) and '.S' (Intel 80960, GNU).
  2411.  
  2412.         The '+' sign indicates that,  starting from the given  directory,
  2413.         all  subdirectories  should be searched recursively for the given
  2414.         file name search pattern.  This addition is  useful  if  a  large
  2415.         software  project  is  divided into several modules with separate
  2416.         subdirectories for each module.  In that case only  the  starting
  2417.         (root-)directory with the requested file name search pattern must
  2418.         be   specified   to   search   the   current  directory  and  all
  2419.         subdirectories.
  2420.  
  2421.         If the file name or the include file specification inside a  file
  2422.         contains a relative path ('./',  '.\', '../' or '..\') it will be
  2423.         translated into  an  absolute  path  starting  from  the  current
  2424.         working directory respectively in case of include files depending
  2425.         on  the  path of the parent file.  Command line wildcards '*' and
  2426.         '?' are possible and will be accepted.
  2427.  
  2428.  
  2429.         REMARKS ON USING OPTIONS
  2430.  
  2431.         NONE OF THE ABOVE DESCRIBED OPTIONS IS PREDEFINED SO IT'S  UP  TO
  2432.         THE  USER HIMSELF TO CUSTOMIZE HIS PREFERRED PROCESSING BEHAVIOUR
  2433.         AND OUTPUT STYLE BY ADDING CONTROL OPTIONS NEEDED THEREFORE.
  2434.         This assumption seems to be the best way to give  the  users  the
  2435.         freedom  of  making  their  own decisions about the features they
  2436.         really need for doing their work.
  2437.  
  2438.  
  2439.  
  2440.                                      - 40 -
  2441.  
  2442.  
  2443.         However,  some of the options should  be  regarded  and  used  as
  2444.         'DEFAULT'  options  to  generate a readable,  complete and useful
  2445.         output file without  unexpected  side  effects.  So  the  minimum
  2446.         default command lines look like
  2447.  
  2448.              CFT -m -ra <files>
  2449.              CST -ra <files>
  2450.  
  2451.         Both  command  sets  generate  a  complete listing containing all
  2452.         items with file name and line reference and a cross reference  id
  2453.         for repeated use (options -ra).  The option -m for CFT forces the
  2454.         output  to  start  with  the  'main'  function  (if  found).  The
  2455.         precompile  option  -P is not strictly necessary though for exact
  2456.         results it should also be set together with the  -T  option.  The
  2457.         standard default command line might be
  2458.  
  2459.              CFT -m -rauspMP -T<type> -cs -Cs -na -Zs -G <file[s]>
  2460.              CST -rapMP -T<type> -cs -Cs -na -Zs -G <file[s]>
  2461.  
  2462.         If you start using CFT and CST for your own business,  take these
  2463.         options as a basic set and try other options to get a feeling for
  2464.         what they are useful and how they affect the output.
  2465.  
  2466.         The large number of options may be confusing  for  beginners  but
  2467.         this  is  the  only  way  to  give  the  users the flexibility of
  2468.         customising their own output. Therefore,  take some time to learn
  2469.         about CFT and CST and their features,  read this manual carefully
  2470.         and make your own experiences with this software.
  2471.  
  2472.         It is possible to declare more than one source file, command file
  2473.         and list file on the command line.  In that  case  they  will  be
  2474.         processed  in  the  order  they appear.  Files and options can be
  2475.         placed  in  mixed  order  on  the  command  line,   there  is  no
  2476.         recommended order for them because all options (also those inside
  2477.         command  files!)  will  be  processed before any source files are
  2478.         scanned.
  2479.  
  2480.         The maximum command line length for DOS  is  127  characters,  so
  2481.         this  is  a  system dependent 'natural' limit for the options and
  2482.         file names being declared.  If you have more  items  to  declare,
  2483.         place them into command list files and file list files,  which do
  2484.         not have such limitations.
  2485.  
  2486.         Options can also be defined by the environment variables CFT  and
  2487.         CST like
  2488.  
  2489.              SET CFT=...
  2490.              SET CST=...
  2491.  
  2492.         To separate single options in the environment string,  spaces are
  2493.         required.  See also the description for the -D option for remarks
  2494.         on environment variable definitions.
  2495.  
  2496.         The rules for the interpretation of options is
  2497.  
  2498.  
  2499.  
  2500.  
  2501.                                      - 41 -
  2502.  
  2503.  
  2504.         1.   if  defined,  all  options  in the environment variables CFT
  2505.              (for CFT) or CST (for CST) will be taken,
  2506.         2.   the command line  options  and  the  option  files  will  be
  2507.              interpreted in the order they appear.
  2508.  
  2509.         If  an  option is declared different more than once then previous
  2510.         declarations will be overwritten by the newer one.
  2511.  
  2512.         If  options  are  represented  by  a  single  character  with  no
  2513.         additional  optional  values possible like -r or -a,  they can be
  2514.         grouped together with a single leading '-' in front like '-rasM',
  2515.         which is the same as '-r -a -s -M'. The last option however,  can
  2516.         have   additions,   for  example  '-rasMmWinMain'  which  can  be
  2517.         evaluated to '-r -a -s -M -mWinMain'.  If an option can  have  an
  2518.         additional  parameter,  the parameter must be specified without a
  2519.         space between the option character. Leaving this space means that
  2520.         no additional parameter is given for this option.
  2521.  
  2522.         File names being composed of drive letter,  directory name,  file
  2523.         name  and  file  extension,  in  the following referred simply as
  2524.         'path name',  are treated by some special procedures to  force  a
  2525.         unique style of their internal representation:
  2526.  
  2527.         -    path  names  are  always  considered not case sensitive,  so
  2528.              there is no difference in upper case,  lower case and  mixed
  2529.              case  path  names  (the reason is that DOS does not make any
  2530.              difference),
  2531.         -    path names containing './', '.\', '../' and '..\' (so called
  2532.              'relative paths') are expanded and transformed into absolute
  2533.              paths,
  2534.         -    the recommended directory delimiter is '/' (UNIX-style),  if
  2535.              a  '\' (DOS-style) is recognised in a path name,  it will be
  2536.              replaced by '/',
  2537.         -    path names are always  expanded  and  transformed  into  the
  2538.              default style
  2539.  
  2540.                   <DRIVE LETTER>:<DIRECTORY PATH>/<FILE NAME>
  2541.  
  2542.              to get a unique representation for every file name that must
  2543.              be handled during processing,
  2544.         -    file  names have a DOS like maximum length of 12 characters:
  2545.              '<8 characters name>.<3 characters extension>', this is also
  2546.              true for the  Windows  NT  and  OS/2  versions  of  the  SXT
  2547.              programs.
  2548.  
  2549.         These   actions  are  done  with  every  path  name  during  file
  2550.         processing.  File names  given  on  the  command  line  are  also
  2551.         transformed.
  2552.  
  2553.         If  you  want  to  perform  database  generation  (option -G) for
  2554.         different projects,  you are responsible  to  separate  them  and
  2555.         avoid overwriting of existing databases.  This can be done either
  2556.         by giving the databases different  names  so  that  the  database
  2557.         files can be placed all in the same directory,  or every database
  2558.  
  2559.  
  2560.  
  2561.  
  2562.                                      - 42 -
  2563.  
  2564.  
  2565.         must be written into its own directory. If you want to access the
  2566.         databases be sure to use  the  correct  name  and/or  path,  also
  2567.         within the BRIEF or MicroEMACS editors.
  2568.  
  2569.  
  2570.         COMMAND LINE EXAMPLES
  2571.  
  2572.         1.   CFT -m -rau *.c
  2573.         This  program  invocation  of  CFT  processes  all files with the
  2574.         extension ".c" in the current directory and generates  an  output
  2575.         file starting with the "main"-function (option -m) for the output
  2576.         tree.  Every function will be displayed with file and line number
  2577.         reference and a cross reference number (option -r). All functions
  2578.         will be shown in lexicographical order (-a),  also undefined ones
  2579.         (-u).
  2580.  
  2581.         2.   CFT  -mWinMain -rausMP -TMSC70,L -Id: -cs -Cs -na -ve:\ -C++
  2582.              *.c ..\*.c *.cpp
  2583.         This invocation is similar to the one described above  with  some
  2584.         extensions.  The  source files from the current (*.c,  *.cpp) and
  2585.         from the parent (..\*.c) directory,  they  will  be  preprocessed
  2586.         (-P)  with  MS-C  7.0 defines for large memory model (-TMSC70,L),
  2587.         the include file path will be taken from the environment variable
  2588.         "INCLUDE" (default for -P) and the path "d:" (-Id:) will also  be
  2589.         searched  for.  The  precompiler  output  is  stored in path "e:"
  2590.         (-ve:\).  C++ extensions and keywords will be recognised if  they
  2591.         occur  (-C++).  The output will start with the "WinMain"-function
  2592.         (-mWinMain).  There will be a sorted call statistic (-cs)  and  a
  2593.         function  summary  for  every  scanned file (-Cs) with additional
  2594.         informations for every function (-s).  The critical function call
  2595.         path for all functions will be calculated and displayed (-na) and
  2596.         the included files of every source file will be shown (-M).
  2597.  
  2598.         3.   CST -S"struct _test" -r *.h -W2 -C++
  2599.         Start  CST  to  scan  all  files  in  the  current directory with
  2600.         extension ".h" for data types.  They will be displayed with  file
  2601.         name  and  line number reference and cross reference number (-r).
  2602.         The output should be  done  for  the  data  type  'struct  _test'
  2603.         (-S"struct _test"). The warning level is set to "2" (-W2).
  2604.  
  2605.         4.   CFT y.c -R -Dmain=main_entry z.c -P x.c
  2606.         Start CFT to produce a reverse calling tree (-R) of the functions
  2607.         found  in  the  files  "x.c",  "y.c"  and  "z.c"  in  the current
  2608.         directory.  The files will be preprocessed (-P) before file scan,
  2609.         the   name   "main"  will  be  replaced  by  "main_entry"  during
  2610.         preprocessing (-Dmain=main_entry).
  2611.  
  2612.         5.   CST $cst1.cmd $cst2.cmd -ve:\tmp @cstfiles +*.h -olist.v1a
  2613.         This invocation of CST receives  its  options  from  the  command
  2614.         files  "cst1.cmd"  and  "cst2.cmd"  and  stores  the preprocessor
  2615.         output in path "e:\tmp" (-ve:\tmp). The files being processed are
  2616.         defined in the source list file "cstfiles"  and  on  the  command
  2617.         line  by  "+*.h".  The  "+*.h"  file  specification  searches the
  2618.         current directory and  all  subdirectories  for  files  with  the
  2619.         extension  ".h".   The  output  file  will  be  named  "list.v1a"
  2620.         (-olist.v1a).
  2621.  
  2622.  
  2623.                                      - 43 -
  2624.  
  2625.  
  2626.  
  2627.         6.   CFT -ra -PGNUINC -TGNU -M c:\gnu\src\*.c c:\gnu\src\*.s -d10
  2628.         CFT scans all files with extension ".c" and ".s" in the directory
  2629.         "c:\gnu\src". They will be preprocessed with an include file path
  2630.         defined in environment variable "GNUINC" (-PGNUINC) for  compiler
  2631.         type  "GNU" (-TGNU).  The output contains all functions (-a) with
  2632.         complete reference information (-r) and a list  of  all  included
  2633.         files  for  every  source  file  (-M).  The  output  tree will be
  2634.         truncated if the nesting level is higher than 10 (-d10).
  2635.  
  2636.         7.   CST *.c
  2637.         CST processes all  files  with  extension  ".c"  in  the  current
  2638.         working  directory.  There are no options specified,  so only the
  2639.         options set by the environment variable 'CST',  if present,  will
  2640.         be  used  to  customise the program execution.  As an example the
  2641.         command line options  used  in  example  6.  can  be  defined  as
  2642.         environment variable CST by 'SET CST=-raMKPGNUINC -TGNU -d10'.
  2643.  
  2644.         8.   CFT -ra -PI960INC -TI960,KB *.c *.s
  2645.         CFT  scans  all files with extension ".c" and ".s" in the current
  2646.         directory.  They will be preprocessed with an include  file  path
  2647.         defined   in   environment  variable  "I960INC"  (-PI960INC)  for
  2648.         compiler type "I960",  'KB' architecture (-TI960,KB).  The output
  2649.         contains  all  functions (-a) with complete reference information
  2650.         (-r).
  2651.  
  2652.         9.   CFT -rRM -gproj40 -Gproj41
  2653.         CFT reads the database named 'proj40' (-g) and produces as output
  2654.         the reverse function  call  tree  (-R)  with  complete  reference
  2655.         information (-r), the (include) file interdependencies (-M) and a
  2656.         new database named 'proj41'.
  2657.  
  2658.         10.  CST -g -Gnew -N
  2659.         CST  reads  the  default  database  (-g)  and  produces as output
  2660.         another database named 'new' (-Gnew).  No other  output  file  is
  2661.         generated (-N).
  2662.  
  2663.         11.  CST -N -OTEST -O+ test.h
  2664.         CST reads the file "test.h", generates no output file (-N), but a
  2665.         byte  offset  calculation  file for data type 'TEST' (-OTEST) and
  2666.         its enclosed type members (-O+).
  2667.  
  2668.  
  2669.  
  2670.  
  2671.  
  2672.  
  2673.  
  2674.  
  2675.  
  2676.  
  2677.  
  2678.  
  2679.  
  2680.  
  2681.  
  2682.  
  2683.  
  2684.                                      - 44 -
  2685.  
  2686.  
  2687.         9    OUTPUT DESCRIPTION AND INTERPRETATION
  2688.  
  2689.         This section gives an overview about the files being generated by
  2690.         CFT and CST and the  interpretation  of  the  results.  Different
  2691.         files  are  produced as output depending on the options being set
  2692.         by the user.  Usually,  if -N is not set,  all  informations  are
  2693.         written  to  the default output file CFT.LST or CST.LST or to the
  2694.         file specified by the -o option.  The internal structure of these
  2695.         files  and  their  meanings  are  described  below.  If  database
  2696.         generation is enabled with option -G, several files are produced.
  2697.         They all have a common database name to identify the  files  that
  2698.         are  related with a project.  The file extension '.DBF' marks the
  2699.         dBASE compatible database files,  the  file  with  the  extension
  2700.         '.CMD'  contains  the  command line options and the file with the
  2701.         extension '.SRC' contains all source files that  were  processed.
  2702.         For  further  informations  refer to the corresponding section in
  2703.         the syntax description.
  2704.  
  2705.  
  2706.         CFT OUTPUT
  2707.  
  2708.         The output file is divided into several  sections.  Some  of  the
  2709.         sections listed are generated by default (-), others are optional
  2710.         (o)  and  only  displayed  if  they are enabled by a command line
  2711.         option.  Also,  the default sections can be customised to produce
  2712.         the  desired  output.  The sections generated for CFT are (in the
  2713.         order they appear):
  2714.  
  2715.         -    file header
  2716.         -    function calltree/called-by hierarchy listing (-r,  -R,  -x,
  2717.              -a, -m, -f, -dn, -V, -l)
  2718.         -    function summary
  2719.         -    multiple  defined  functions  and  their  location  (only if
  2720.              detected)
  2721.         -    overloaded functions and their location (only if detected)
  2722.         o    undefined functions (-u)
  2723.         o    function call statistics (-c[s])
  2724.         o    function caller/member relations (-Z[s])
  2725.         o    function call cross reference table (-z)
  2726.         o    critical function call path (-n[a])
  2727.         o    source file - include file dependency (-M)
  2728.         o    function tables for source files (-C[s], -s, -q)
  2729.         -    file information summary (-p, -q)
  2730.  
  2731.         Each function is displayed like:
  2732.  
  2733.              int test()  (1) <DMPCA> <TEST.C, 100>
  2734.  
  2735.         with the following meanings
  2736.  
  2737.              - int          : function return type
  2738.              - test()       : function name
  2739.              - (1)          : function reference number
  2740.  
  2741.  
  2742.  
  2743.  
  2744.  
  2745.                                      - 45 -
  2746.  
  2747.  
  2748.              - <DMPCA>      : found as (one or more of)
  2749.                                  D = definition,
  2750.                                  M = macro,
  2751.                                  P = prototype,
  2752.                                  C = function call,
  2753.                                  A = assembler function
  2754.              - <TEST.C, 100>: file name, line number
  2755.  
  2756.         The line number is the line where the function  definition  block
  2757.         starts  with  its initial '{' and not the line where the function
  2758.         name resides.  I think that this is the best solution because  it
  2759.         is  the point where we go really inside the function block.  This
  2760.         convention is also used by source level debuggers which point  on
  2761.         the line with the opening brace on function entry.
  2762.  
  2763.  
  2764.         CST OUTPUT
  2765.  
  2766.         The  output  file  is divided into several sections.  Some of the
  2767.         sections listed are generated by default (-), others are optional
  2768.         (o) and only displayed if they are  enabled  by  a  command  line
  2769.         option.  Also,  the default sections can be customised to produce
  2770.         the desired output.  The sections generated for CST are  (in  the
  2771.         order they appear):
  2772.  
  2773.         -    file header
  2774.         -    data structure calltree/called-by hierarchy listing (-r, -R,
  2775.              -x, -a, -m, -f, -dn)
  2776.         -    data type summary
  2777.         -    multiple  defined  data  types  and  their location (only if
  2778.              detected)
  2779.         o    data type call statistics (-c[s])
  2780.         o    data type caller/member relations (-Z[s])
  2781.         o    data type call cross reference table (-z)
  2782.         o    maximum data type nesting (-n[a])
  2783.         o    source file - include file dependency (-M)
  2784.         o    data type tables for source files (-C[s], -s, -q)
  2785.         -    file information summary (-p, -q)
  2786.  
  2787.         Each data type is displayed like:
  2788.  
  2789.              struct _test  (1) <BSUCE> <TEST.C, 90> <TEST.C, 60>
  2790.  
  2791.         with the following meanings
  2792.  
  2793.              - struct _test : type specifier
  2794.              - (1)          : reference number
  2795.              - <BSUCE>      : data type (one/none of):
  2796.                                  B = basic type (void, char, int, ...),
  2797.                                  S = struct,
  2798.                                  U = union,
  2799.                                  C = class,
  2800.                                  E = enum
  2801.  
  2802.  
  2803.  
  2804.  
  2805.  
  2806.                                      - 46 -
  2807.  
  2808.  
  2809.              - <TEST.C, 90> : file name, line number of type definition
  2810.                               (only printed if necessary)
  2811.              - <TEST.C, 60> : file name, line number of basic type
  2812.                               definition
  2813.  
  2814.         The two locations for the data type can occur if the data type is
  2815.         first defined and later assigned via 'typedef'  or  by  '#define'
  2816.         (if -P is not set) to another data type name:
  2817.  
  2818.         test.c:   ...
  2819.         line 60:  struct xyz {...};
  2820.                   ...
  2821.         line 90:  typedef struct xyz struct _test;
  2822.                   ...
  2823.  
  2824.         Their  definition  is on different lines but both data type names
  2825.         refer to the same data structure.
  2826.  
  2827.         Like the convention used for functions,  the line number  is  the
  2828.         line  where  the  structure,  union,  enumeration  or  class type
  2829.         definition block starts with its initial '{'  and  not  the  line
  2830.         where the type name resides.
  2831.  
  2832.         For  an  example session and more detailed informations about the
  2833.         generated output of CFT and CST see the file EXAMPLE.DOC.
  2834.  
  2835.  
  2836.         OUTPUT INTERPRETATION
  2837.  
  2838.         Besides the hierarchical structure chart of the function and data
  2839.         type relationships,  the resulting output contains several useful
  2840.         informations   about   the   program   which   can  be  used  for
  2841.         optimization, reuse or maintenance purposes. Identifying the most
  2842.         frequently called functions is a good way to find candidates  for
  2843.         further  optimization.  Low-level functions with many callers but
  2844.         no called subfunctions are ideal for  reuse.  Functions  with  no
  2845.         callers  may  be  obsolete if the function is also not called via
  2846.         function pointers, and can be discarded therefore.  The chance to
  2847.         find  errors in complex functions with many lines of source code,
  2848.         many called functions and a lot of  control  statements  is  much
  2849.         bigger than in simple functions.
  2850.  
  2851.  
  2852.  
  2853.  
  2854.  
  2855.  
  2856.  
  2857.  
  2858.  
  2859.  
  2860.  
  2861.  
  2862.  
  2863.  
  2864.  
  2865.  
  2866.  
  2867.                                      - 47 -
  2868.  
  2869.  
  2870.         10   INTEGRATION INTO PROGRAM DEVELOPMENT ENVIRONMENTS
  2871.  
  2872.         Invoking  CFT  and CST directly from inside editors or integrated
  2873.         programming environments (IDE) and displaying the results can  be
  2874.         a  very useful feature during program development.  With advanced
  2875.         IDE's like that of Borland C++ or Microsoft PWB this is  an  easy
  2876.         task.
  2877.  
  2878.         The  Borland  IDE has in its system menu a section with 'transfer
  2879.         items.  It contains programs that can be invoked from inside  the
  2880.         IDE like TASM or GREP. To add CFT and CST as new entries you have
  2881.         to go to the OPTIONS menu and open 'TRANSFERS...'.  Choose a free
  2882.         entry in the table and select EDIT.  A window will  open  with  3
  2883.         edit  lines.  In first line called 'Program Title' you must write
  2884.         'C~FT' resp.  'C~ST' as the name being displayed in the  transfer
  2885.         section. The '~' prepends the hot-keys 'F' and 'S'. In the second
  2886.         line   called  'Program  Path'  you  must  write  'CFTIDE'  resp.
  2887.         'CSTIDE',  maybe with the complete path,  if necessary.  'CFTIDE'
  2888.         and  'CSTIDE' are two batch files which perform the invocation of
  2889.         CFT resp.  CST together with the necessary options.  These  batch
  2890.         files  are  part  of the CXT package,  you can change the options
  2891.         defined there if you need other ones.  In the third  line  called
  2892.         'Command Line' you must write the macro commands '$EDNAME $NOSWAP
  2893.         $CAP  EDIT'.  These  macros transfer the file name in the current
  2894.         edit window ($EDNAME) to the batch file, suppress window swapping
  2895.         ($NOSWAP) and capture the  processing  results  in  an  own  edit
  2896.         window ($CAP EDIT).  The last step is to save these entries, then
  2897.         the integration is completed and CFT and CST can be  used  as  if
  2898.         they were built-in functions. The processing results are shown in
  2899.         an edit window which can be scrolled, resized or moved. By adding
  2900.         CFT  and  CST  to the IDE it is much easier for the programmer to
  2901.         use these tools.
  2902.  
  2903.  
  2904.  
  2905.  
  2906.  
  2907.  
  2908.  
  2909.  
  2910.  
  2911.  
  2912.  
  2913.  
  2914.  
  2915.  
  2916.  
  2917.  
  2918.  
  2919.  
  2920.  
  2921.  
  2922.  
  2923.  
  2924.  
  2925.  
  2926.  
  2927.  
  2928.                                      - 48 -
  2929.  
  2930.  
  2931.         11   TOOLS FOR DATABASE PROCESSING
  2932.  
  2933.         To access  informations  stored  in  a  database,  the  following
  2934.         utilities are available for the SXT programs:
  2935.  
  2936.              CFTN      C Function Tree Navigator
  2937.              CSTN      C Structure Tree Navigator
  2938.              DFTN      DBASE Function Tree Navigator
  2939.              FFTN      FORTRAN Function Tree Navigator
  2940.              LFTN      LISP Function Tree Navigator
  2941.  
  2942.         They  can  be  used  to recall the file name and line number of a
  2943.         specific item (function or data type) from the database.  If  the
  2944.         requested  item  is  found in the database,  it will be displayed
  2945.         with its location where it is defined or where it  is  found  for
  2946.         the   first   time  if  there  was  no  definition  found  during
  2947.         processing.
  2948.  
  2949.         As an additional feature editors like BRIEF 3.0, QEDIT 2.1/3.0 or
  2950.         MicroEMACS 3.11 can be invoked directly with the informations  to
  2951.         open the target file and to move the cursor to the line where the
  2952.         searched  item  is  located.  For  BRIEF there are several macros
  2953.         available to perform searching inside  the  editor.  A  new  edit
  2954.         window  with  the file at the location of the requested item will
  2955.         be opened if the search  was  successful.  Also  both  MicroEMACS
  2956.         editor versions for DOS and WINDOWS are supported.  Some of these
  2957.         actions are also possible for QEDIT,  with slight limitations due
  2958.         to the macro programming capabilities.
  2959.  
  2960.         Other user programmable editors which should be able to work with
  2961.         CFTN  and  CSTN  are  e.g.   CRISP  and  Codewright  (both  BRIEF
  2962.         compatible), EPSILON, ME, KEDIT, Multi-Edit, JED, GNU-EMACS ports
  2963.         like DEMACS or OEMACS,  the  Microsoft  editor  M  or  integrated
  2964.         development  environments like Borland IDE or Microsoft PWB (this
  2965.         list may not be complete). You can try to integrate CFTN and CSTN
  2966.         into these systems by using the BRIEF,  QEDIT or MicroEMACS macro
  2967.         files as examples for your own integration development.
  2968.  
  2969.         The  version  numbers  for  the  editors mentioned in this manual
  2970.         indicate those versions for which the described capabilities have
  2971.         been tested.
  2972.  
  2973.         PRECOMPILED SOURCE FILES
  2974.  
  2975.         Sometimes,  if the precompile option -P was used to  process  the
  2976.         C/C++  source  files  related  with the database,  the results of
  2977.         searches seem to be wrong.  This can happen if an  identifier  in
  2978.         the  source  code  is  in  fact  defined  as a macro and has been
  2979.         exchanged during  preprocessing  so  that  the  resulting  source
  2980.         processed  by  the analyser is different from the original source
  2981.         and the cursor will point to an obviously  wrong location or  the
  2982.         search will fail.  An identifier which is in fact a macro name is
  2983.         unknown  and  not  accessible  after  precompiling.  It  is  also
  2984.         possible  that a function being used in the original source could
  2985.         not be found in the database.  The reason is that the function is
  2986.         in   fact  a  'function  like'  macro  and  was  replaced  during
  2987.  
  2988.  
  2989.                                      - 49 -
  2990.  
  2991.  
  2992.         preprocessing.  If different named macros are  defined  equal,  a
  2993.         search  for  an  item  may  point  to  another  location than the
  2994.         requested.  If the -P option is not set,  the same item can  have
  2995.         several 'alias'- names due to macro defining.  If the source code
  2996.         contains explicit #line numbers,  searching for a  specific  line
  2997.         may  also  fail.  Keep  these  exceptions  in  mind for a correct
  2998.         interpretation the results when using the database.
  2999.  
  3000.         IMPORTANT NOTICE
  3001.  
  3002.         Recalling informations from the database  may  not  be  valid  if
  3003.         files  being processed were edited and changed after the database
  3004.         generation has been performed. Errors can result like pointing to
  3005.         wrong files and/or lines if source lines  have  been  deleted  or
  3006.         inserted,  failed  searches  if  names  have  changed  or  failed
  3007.         accesses to files which may have been renamed,  moved or deleted.
  3008.         To avoid these errors,  a consistency check for the file creation
  3009.         date/time and file size will be performed by the recall programs.
  3010.         If inconsistencies are recognised, the user will be informed that
  3011.         the  database  is  not  up-to-date  and  should  be  updated   by
  3012.         processing the source files again.
  3013.  
  3014.  
  3015.         IMPORTANT  NOTICE TO DEVELOPERS USING THE DATABASE FROM THEIR OWN
  3016.         PROGRAMS
  3017.  
  3018.         There is absolutely  no  guarantee  that  the  internal  database
  3019.         structure will remain unchanged.  The internal database structure
  3020.         may change without notice.
  3021.  
  3022.  
  3023.         COMMAND LINE SYNTAX DESCRIPTION
  3024.  
  3025.         SYNTAX:   CFTN [options] pattern
  3026.                   CSTN [options] pattern
  3027.                   DFTN [options] pattern
  3028.                   FFTN [options] pattern
  3029.                   LFTN [options] pattern
  3030.  
  3031.         OPTIONS
  3032.  
  3033.         -Eeditor
  3034.         Specifies the editor command line for option -e,  overwrites  the
  3035.         default  and  the  environment  values.  See  the  section  about
  3036.         environment variables for further informations about the required
  3037.         format.
  3038.  
  3039.         -F
  3040.         Print all file names which are related with  the  database.  This
  3041.         option  is  useful  to get a complete overview about all files of
  3042.         the project.
  3043.  
  3044.  
  3045.  
  3046.  
  3047.  
  3048.  
  3049.  
  3050.                                      - 50 -
  3051.  
  3052.  
  3053.         -a
  3054.         Print all function/data type names.  Useful to generate a list of
  3055.         items, for example as input to other programs.
  3056.  
  3057.         -B
  3058.         Same as -a,  but prints additionally the internal database record
  3059.         number. Used by BRIEF macros.
  3060.  
  3061.         -bform
  3062.         Run search in batch-mode, this means that,  if the requested item
  3063.         was  found,  the  location  will be displayed on a single line as
  3064.         "file name line number" (DEFAULT STYLE),  otherwise there will be
  3065.         no output that the search failed. The output style can be changed
  3066.         by  specifying  'form'  to overwrite the default style.  Like for
  3067.         option -E you can specify the exact locations where the file name
  3068.         and line number should be inserted by defining  a  format  string
  3069.         with   %s   and  %d  (See  also  the  section  about  environment
  3070.         variables).  For example,  the format to generate a command  line
  3071.         for invoking BRIEF, QEDIT or MicroEMACS would look like
  3072.  
  3073.              cstn -b"b -m\"goto_line %d\" %s" ...         (BRIEF)
  3074.              cstn -b"q %s -n%d" ...                       (QEDIT)
  3075.              cstn -b"me -G%d %s"                          (MicroEMACS)
  3076.  
  3077.         This option gives you a great flexibility in generating an output
  3078.         for  your own purposes,  for example to write a batch file or for
  3079.         further use in other programs.
  3080.  
  3081.         -e
  3082.         If the requested item is found,  an editor  will  be  invoked  to
  3083.         display  the file containing the requested item.  There are three
  3084.         different ways to specify the editor command line  (evaluated  in
  3085.         that order):
  3086.  
  3087.         1)   use option -E,
  3088.         2)   define  the  environment  variables  CFTNEDIT,  CSTNEDIT  or
  3089.              CXTNEDIT,
  3090.         3)   if nothing is specified,  BRIEF as the  default  editor  (if
  3091.              present)  will be invoked with the file name and line number
  3092.              of the item to move the cursor to its location.  Ensure that
  3093.              the  PATH  environment variable is set correctly,  including
  3094.              the path for the BRIEF directory.
  3095.  
  3096.         -fname
  3097.         Use 'name' as base name (path and file name) for database  files.
  3098.         It  is  also  possible  to  use  environment variables (CFTNBASE,
  3099.         CSTNBASE, CXTNBASE) for the definition of the database names.  If
  3100.         -f and environment variables are not set,  a DEFAULT NAME will be
  3101.         used (see also option -G from CFT and  CST  syntax  description).
  3102.         This  allows  the  use  of  different  databases,   for  example,
  3103.         generated for different projects.  See  also  the  section  about
  3104.         environment variables for further information.
  3105.  
  3106.  
  3107.  
  3108.  
  3109.  
  3110.  
  3111.                                      - 51 -
  3112.  
  3113.  
  3114.         -r#
  3115.         This option prints the location for a selected item with matching
  3116.         pattern  and  record number #.  This option requires -b.  Used by
  3117.         BRIEF macros.
  3118.  
  3119.         -Ritem
  3120.         Print a cross reference list of every occurrence of  'item'  with
  3121.         complete file name and line number.
  3122.  
  3123.         -Dfile
  3124.         Print a list with the contents of 'file'.
  3125.  
  3126.         -o[name]
  3127.         Print output to file 'name'.  If 'name' is not specified, DEFAULT
  3128.         NAMES are used: CFTN.OUT resp. CSTN.OUT.
  3129.  
  3130.         pattern
  3131.         The item to search for in the database.  This  can  either  be  a
  3132.         function name (CFTN) or a data type name (CSTN).  There are three
  3133.         different ways of searching depending how 'pattern' is given:
  3134.  
  3135.         pattern        exact search,
  3136.         pattern*       the beginning of the item must match with pattern
  3137.         *pattern       a substring must match with pattern
  3138.  
  3139.         If the item  to  search  for  consists  of  more  than  one  word
  3140.         (contains  spaces),  the  search  pattern  must  be 'quoted' like
  3141.         "struct _iobuf" to ensure that these  words  are  interpreted  as
  3142.         single pattern.
  3143.  
  3144.  
  3145.         RETURN VALUES
  3146.  
  3147.         The  following  values are returned to DOS or the calling program
  3148.         to report the result of the database search:
  3149.  
  3150.         -    100  searched item not found,
  3151.         -    101  searched item found,
  3152.         -    102  searched item found,  but the source file may have been
  3153.                   changed  (creation date and/or file size are not equal)
  3154.                   since the creation of the  database  (database  is  not
  3155.                   up-to-date).
  3156.  
  3157.         The  returned  value  can be used to decide what action should be
  3158.         done for different results,  for example,  if the database is not
  3159.         up-to-date.
  3160.  
  3161.  
  3162.         ENVIRONMENT VARIABLES
  3163.  
  3164.         CFTNEDIT, CSTNEDIT, CXTNEDIT:
  3165.         The  editor  to  invoke  can be defined either by option -e or by
  3166.         defining the environment variables CFTNEDIT (for CFTN),  CSTNEDIT
  3167.         (for  CSTN) or the commonly used variable CXTNEDIT (for both CFTN
  3168.         and CSTN) with the format string of the editor  of  your  choice.
  3169.         The format string can be used to specify the place where the file
  3170.  
  3171.  
  3172.                                      - 52 -
  3173.  
  3174.  
  3175.         name  and  the  line number should be inserted to give additional
  3176.         informations to the editor.  Use %s for the file name and %d  for
  3177.         the  line  number.  For  example,  the  invocation of the default
  3178.         editor BRIEF could be defined like
  3179.  
  3180.              SET CFTNEDIT=b -m"goto_line %d" %s
  3181.              SET CSTNEDIT=b -m"goto_line %d" %s
  3182.              SET CXTNEDIT=b -m"goto_line %d" %s
  3183.  
  3184.         where 'b' is the BRIEF editor,  '-m' specifies  the  macro  being
  3185.         invoked  when BRIEF starts,  the macro name 'goto_line' with '%d'
  3186.         as the place to insert the line number and '%s' as the place  for
  3187.         the  file  name.  Note  that  this  example cannot be used on the
  3188.         command line with -E option because of the quotes. It is possible
  3189.         to change the order of %d and %s if another editor is used.
  3190.  
  3191.         Here are additional  configuration  examples  for  other  popular
  3192.         editors (examples are given for CFTN, similar for CSTN):
  3193.  
  3194.         EDIT (MS-DOS 5.0):  SET CFTNEDIT=edit %s  or  -E"edit %s"   or
  3195.                             SET CFTNEDIT=edit     or  -Eedit
  3196.  
  3197.         VDE 1.62:           SET CFTNEDIT=vde %s   or  -E"vde %s"    or
  3198.                             SET CFTNEDIT=vde      or  -Evde
  3199.  
  3200.         QEDIT 2.1/3.0:      SET CFTNEDIT=q %s -n%d   or   -E"q %s -n%d"
  3201.  
  3202.         MicroEMACS 3.11:    SET CFTNEDIT=me -G%d %s  or   -E"me -G%d %s"
  3203.  
  3204.         The described notation allows the user to customise CFTN and CSTN
  3205.         with  his  preferred  editor  and  to  perform additional actions
  3206.         during invocation. If your editor supports macro programming like
  3207.         BRIEF you are free to write your own macros to do similar  things
  3208.         like  the CXT.CM macro given for BRIEF 3.0 does.  I think this is
  3209.         the most flexible way to give users control about this option and
  3210.         to help them working with their preferred programming environment
  3211.         and development tools.
  3212.  
  3213.         CFTNBASE, CSTNBASE, CXTNBASE:
  3214.         These environment variables can be used to specify  the  name  of
  3215.         the  database.  Similar  to  the  editor  environment  variables,
  3216.         CFTNBASE and CSTNBASE are related to CFTN and CSTN  and  CXTNBASE
  3217.         is  used for both.  For example,  to specify the database 'proj1'
  3218.         located in directory 'd:\develop\projects' type
  3219.  
  3220.              SET CFTNBASE=d:\develop\projects\proj1
  3221.              SET CSTNBASE=d:\develop\projects\proj1
  3222.  
  3223.         for a separate definition or
  3224.  
  3225.              SET CXTNBASE=d:\develop\projects\proj1
  3226.  
  3227.         for a common definition of the database name.
  3228.  
  3229.  
  3230.  
  3231.  
  3232.  
  3233.                                      - 53 -
  3234.  
  3235.  
  3236.         COMMAND LINE EXAMPLES
  3237.  
  3238.         1)   CFTN *
  3239.         Displays all functions in lexicographical order with their return
  3240.         types, file names and line numbers.  Gives a short overview about
  3241.         all functions being found.
  3242.  
  3243.         2)   CSTN -e *
  3244.         Edit  all data types in lexicographical order,  use default or by
  3245.         environment variable CSTNEDIT or CXTNEDIT defined editor.
  3246.  
  3247.         3)   CFTN -fproject1 -Evde -e main
  3248.         Search database named 'project1' for  function  'main'  and  edit
  3249.         with editor 'vde'.
  3250.  
  3251.         4)   CSTN -b "union REGS"
  3252.         Search for data type 'union REGS' and display, if found, the file
  3253.         name and line number
  3254.  
  3255.         5)   CSTN -e -E"q %s -n%d" -fcft tmbuf
  3256.         Search database 'cft' for data type 'tmbuf' and invoke, if found,
  3257.         the editor 'q' (QEDIT 2.1/3.0) with the file name and line number
  3258.  
  3259.  
  3260.         SEARCHING INSIDE BRIEF (Version 3.0)
  3261.  
  3262.         This  feature  is  one  of the most powerful enhancements for the
  3263.         BRIEF editor and offers the user full control over  the  complete
  3264.         source  code  of software projects no matter how big they are and
  3265.         how many files they include.  It extends the BRIEF  editor  to  a
  3266.         comfortable hypertext source code browser and locator system. The
  3267.         browser  allows  its  user  to  find  and  read various important
  3268.         program constructs like functions and data types in several files
  3269.         simultaneously and moving between them. The complete project with
  3270.         several source  and  include  files  appears  as  if  it  were  a
  3271.         'whole-part'. The browser helps the programmer to learn about the
  3272.         existing  program  structures  and supports him in developing new
  3273.         and  maintaining  existing  code.  The  programmer  can  use  the
  3274.         generated  output files CFT.LST or CST.LST (or the one he created
  3275.         with the -o option) to walk along the hierarchy tree chart and to
  3276.         select from there the  function  or  data  type  that  should  be
  3277.         displayed in detail.
  3278.  
  3279.         The following features are implemented as macros:
  3280.  
  3281.         -    searching for a specific item, tagged or marked
  3282.         -    building menus of all defined items
  3283.         -    building menus of all references to a specific item
  3284.         -    building menus of all processed files
  3285.         -    building menus of all items defined in the current file
  3286.         -    searching for a specific item cross reference number
  3287.         -    changing the database name
  3288.  
  3289.         Every  function  and  data  type  can  be  accessed  with  just a
  3290.         keystroke by moving the cursor on it ("tagging") and executing  a
  3291.         macro  to  locate  the  item  and  zoom into the file where it is
  3292.  
  3293.  
  3294.                                      - 54 -
  3295.  
  3296.  
  3297.         defined.  The user does no longer have to remember the file names
  3298.         and  locations where the functions and data types are defined nor
  3299.         does he have to change  the  files,  directories  and  drives  to
  3300.         access the files manually.
  3301.  
  3302.         It  is  possible  to  build  interactive  dialog  menus  with all
  3303.         functions or data types in lexicographical order and to select an
  3304.         item to display.  This is very useful to  get  a  quick  overview
  3305.         about  all  accessible  functions  and  data  types  of the whole
  3306.         project.  It is also possible to build an interactive dialog menu
  3307.         with  all file names in lexicographical order which are stored in
  3308.         the database and to select one file to open for edit. Other menus
  3309.         are available for file contents lists and item cross  references.
  3310.         All  informations  to  perform  these  actions  are stored in the
  3311.         databases generated by processing  the  files  related  with  the
  3312.         project.
  3313.  
  3314.         To invoke CFTN and CSTN inside BRIEF,  the macro file CXT.CM must
  3315.         be loaded (with <F9> CXT.CM),  which makes the implemented macros
  3316.         available. These macros are
  3317.  
  3318.              MACRO NAME          KEY ASSIGNMENT (defined in CXTKEYS.CM)
  3319.  
  3320.              cft                 Shift F1
  3321.              cftmenu             Shift F2
  3322.              cftxrefmenu         Shift F3
  3323.              cftxrefmenuagain    Shift F4
  3324.              cftdefmenu          Shift F7
  3325.              cftfilemenu         Shift F8
  3326.              cftfind             Shift F11
  3327.              cftbase             Shift F12
  3328.  
  3329.              cst                 Ctrl F1
  3330.              cstmenu             Ctrl F2
  3331.              cstxrefmenu         Ctrl F3
  3332.              cstxrefmenuagain    Ctrl F4
  3333.              cstdefmenu          Ctrl F7
  3334.              cstfilemenu         Ctrl F8
  3335.              cstfind             Ctrl F11
  3336.              cstbase             Ctrl F12
  3337.  
  3338.              cxtbase             Alt Tab
  3339.              cxtsearchxref       Ctrl Tab
  3340.              cxthelp             <unassigned>
  3341.  
  3342.         This  macro key assignment list is also available within BRIEF as
  3343.         a help screen which can be invoked by the  macro  'cxthelp'.  The
  3344.         CXT help information is not part of the BRIEF help system because
  3345.         this would need modifications of the original BRIEF help files.
  3346.  
  3347.         Instead  of  loading  the  file CXT.CM and typing the macro names
  3348.         manually,  you can load the macro file CXTKEYS.CM which  performs
  3349.         automatic  loading  of the CXT.CM file if any of the above listed
  3350.         macros is invoked with a hot-key.  To simplify working with  this
  3351.         package,  the CXTKEYS.CM macro file also contains key assignments
  3352.         for  the  macros.  These  hot-keys  offer  a  "point  and  shoot"
  3353.  
  3354.  
  3355.                                      - 55 -
  3356.  
  3357.  
  3358.         hypertext like feeling. The macro source file CXTKEYS.CB contains
  3359.         the  source  code  for  CXTKEYS.CM  so  that you are able to make
  3360.         changes like the key assignments for your personal  needs  or  to
  3361.         move the initialization function to the BRIEF start-up macro file
  3362.         (For  further  informations  about  BRIEF  macros  see  the BRIEF
  3363.         manuals).  To load these macros and to  execute  CFTN  and  CSTN,
  3364.         which are invoked from inside BRIEF, be sure to set the directory
  3365.         path correctly. It is also necessary to allow access to the macro
  3366.         file  DIALOG.CM  which  contains  the  functions  for dialog menu
  3367.         building and processing.
  3368.  
  3369.         A search can be started by simply moving the cursor on  the  item
  3370.         to  search  for or by marking a block with the item (necessary if
  3371.         search pattern contains more than one word like 'struct xyz') and
  3372.         then running one of the following macros (or press hot-keys):
  3373.  
  3374.              <F10> cft                     (function search)
  3375.              <F10> cst                     (data type search)
  3376.  
  3377.         It is also possible to type the name of the item  to  search  for
  3378.         manually. To do this you must run one of the following macros:
  3379.  
  3380.              <F10> cftfind <item>          (function search)
  3381.              <F10> cstfind <item>          (data type search)
  3382.  
  3383.         If  the  search  was  successful,  a  new  window  with  the file
  3384.         containing the item will be opened and the cursor will be  placed
  3385.         at  the  line where the item is located.  If inconsistencies have
  3386.         been detected,  the user will be informed.  If the requested item
  3387.         or  the  source file containing the item is not found,  a message
  3388.         will be given. The macros for building the function and data type
  3389.         dialog menu are
  3390.  
  3391.              <F10> cftmenu                 (function menu)
  3392.              <F10> cstmenu                 (data type menu)
  3393.  
  3394.         You can scroll through the  entries  and  select  an  item  which
  3395.         should  be displayed.  To access databases other than the default
  3396.         ones, there are two ways to change the base names:
  3397.  
  3398.         1)   Set the environment variables CFTNBASE, CSTNBASE or CXTNBASE
  3399.              (see description above).  By loading the macro  file  CXT.CM
  3400.              these variables will be used for initialization.
  3401.  
  3402.         2)   To change the base names from inside BRIEF,  there are three
  3403.              macros to do this.  They overwrite the initial values  given
  3404.              by the environment variables:
  3405.  
  3406.              <F10> cftbase     change base name for function search
  3407.              <F10> cstbase     change base name for data type search
  3408.              <F10> cxtbase     change both CFT and CST base name
  3409.  
  3410.  
  3411.  
  3412.  
  3413.  
  3414.  
  3415.  
  3416.                                      - 56 -
  3417.  
  3418.  
  3419.         With  these features it is possible to set default values for the
  3420.         database files or to change between different  databases  without
  3421.         leaving BRIEF which gives the user a maximum of flexibility.  You
  3422.         can display a menu list with all source files being  scanned  for
  3423.         the database by typing
  3424.  
  3425.              <F10> cftfilemenu             (CFT file menu)
  3426.              <F10> cstfilemenu             (CST file menu)
  3427.  
  3428.         With  this  feature  you can get a quick overview about all files
  3429.         related with the database.  Other menu driven options concern the
  3430.         displaying  of all cross references to a specific item (see macro
  3431.         'cst' for informations about marking) with the macros
  3432.  
  3433.              <F10> cftxrefmenu             (CFT cross reference menu)
  3434.              <F10> cftxrefmenuagain        (show previous menu again)
  3435.              <F10> cstxrefmenu             (CST cross reference menu)
  3436.              <F10> cstxrefmenuagain        (show previous menu again)
  3437.  
  3438.         and the displaying of a file contents list for the actual  source
  3439.         file with the macros
  3440.  
  3441.              <F10> cftdefmenu              (CFT file menu)
  3442.              <F10> cstdefmenu              (CST file menu)
  3443.  
  3444.         To  search for the first appearance of a specific cross reference
  3445.         number like '(123)' in a CFT or CST output listing file, move the
  3446.         cursor to the reference number and type
  3447.  
  3448.              <F10> cxtsearchxref           (search cross reference)
  3449.  
  3450.         The macro extracts the complete number and searches for its first
  3451.         occurrence by starting from the beginning  of  the  output  file.
  3452.         With  this  macro  you can move quickly from any reference to its
  3453.         initial description.
  3454.  
  3455.         All the above described macro functions are defined in the  BRIEF
  3456.         macro file CXT.CB. These macros make extensive use of the several
  3457.         options  of  CFTN  resp.  CSTN,  which  are  described earlier in
  3458.         detail.
  3459.  
  3460.  
  3461.         SEARCHING INSIDE QEDIT (2.1 and 3.0)
  3462.  
  3463.         The popular shareware editor QEDIT  with  its  macro  programming
  3464.         capabilities  allows,  like  the  BRIEF editor,  the searching of
  3465.         functions and data types from inside the  editor.  The  following
  3466.         examples for QEDIT macros act,  with slight limitations, like the
  3467.         BRIEF macros 'cft' and 'cst':
  3468.  
  3469.  
  3470.  
  3471.  
  3472.  
  3473.  
  3474.  
  3475.  
  3476.  
  3477.                                      - 57 -
  3478.  
  3479.  
  3480.         CFT function searching, assigned to <SHIFT F9>:
  3481.  
  3482.         #f9  MacroBegin MarkWord Copy Dos 'cftn -b ' Paste '>tmp'  Return
  3483.              Return   EditFile  'tmp'  Return  AltWordSet  MarkWord  Copy
  3484.              DefaultWordSet EditFile Paste Return EditFile  'tmp'  Return
  3485.              EndLine  CursorLeft  MarkWord  Copy  Quit  NextFile GotoLine
  3486.              Paste Return
  3487.  
  3488.         CST data type searching, assigned to <SHIFT F10>:
  3489.  
  3490.         #f10 MacroBegin MarkWord Copy Dos 'cstn -b ' Paste '>tmp'  Return
  3491.              Return   EditFile  'tmp'  Return  AltWordSet  MarkWord  Copy
  3492.              DefaultWordSet EditFile Paste Return EditFile  'tmp'  Return
  3493.              EndLine  CursorLeft  MarkWord  Copy  Quit  NextFile GotoLine
  3494.              Paste Return
  3495.  
  3496.         These  QEDIT  macro  definitions   can   be   placed   into   the
  3497.         'qconfig.dat'  configuration  file  and added to 'q.exe' with the
  3498.         'qconfig.exe' configuration utility (For additional details about
  3499.         QEDIT macro programming see the  QEDIT  documentation).  The  two
  3500.         macros  perform  the  following  actions:  mark the current word,
  3501.         execute the CFTN or CSTN database search for the marked word  via
  3502.         dos and redirect the output to file 'tmp',  read target file name
  3503.         from 'tmp' and open target file,  read line number from 'tmp' and
  3504.         go to the selected line.
  3505.  
  3506.         These macros are working almost similar to those used from BRIEF,
  3507.         but  they have some limitations in their functionality due to the
  3508.         limited capabilities of the QEDIT macro programming language:
  3509.  
  3510.         -    there is no error check for a correct cursor location,
  3511.         -    the searched item must always be a single word  like  'main'
  3512.              or  'size_t',  a combined pattern like 'struct iobuf' cannot
  3513.              be searched,
  3514.         -    there is no error check if  the  search  was  successful  or
  3515.              failed or the database is not up-to-date,
  3516.         -    if the target file is the same as that from which the search
  3517.              started and other additional files are also open (QEDIT ring
  3518.              buffer), probably a wrong file will be accessed,
  3519.         -    the name of the database cannot be changed, the searches are
  3520.              performed  either with the default database or those defined
  3521.              by the environment variables.
  3522.  
  3523.  
  3524.         SEARCHING INSIDE MicroEMACS (Version 3.11, DOS & WINDOWS)
  3525.  
  3526.         The latest editor which is now supported with macros for database
  3527.         access is MicroEMACS 3.11. The macro file is named CXT_ME.CMD and
  3528.         should be place in the  MircoEMACS  directory.  This  macro  file
  3529.         works with the DOS and the WINDOWS version of MicroEMACS 3.11.
  3530.  
  3531.         The following macros are available:
  3532.  
  3533.         -    cft       function search for tagged item
  3534.         -    cst       data type search for tagged item
  3535.         -    cftmark   function search for marked item
  3536.  
  3537.  
  3538.                                      - 58 -
  3539.  
  3540.  
  3541.         -    cstmark   data type search for marked item
  3542.         -    cftfind   function search for user defined item
  3543.         -    cstfind   data type search for user defined item
  3544.         -    cftfile   list of all CFT files
  3545.         -    cstfile   list of all CST files
  3546.         -    cftbase   set CFT database name
  3547.         -    cstbase   set CST database name
  3548.         -    cxtbase   set both CFT and CST database name
  3549.  
  3550.         They can be invoked by loading the macro file CXT_ME.CMD with
  3551.  
  3552.              ESC CTRL+S CXT_ME.CMD
  3553.  
  3554.         and running the macro with
  3555.  
  3556.              ESC CTRL+E <macro name>
  3557.  
  3558.         If  the macros are used with the MicroEMACS WINDOWS version,  you
  3559.         may have to change the DOSEXEC.PIF file,  which is  part  of  the
  3560.         MicroEMACS  3.11  distribution  package.  During  the  CXT  macro
  3561.         execution,  the shell command may stop after execution and  waits
  3562.         for  the  <return>  key  pressed  to  continue.   To  avoid  this
  3563.         interruption,  you can enable it by  editing  the  PIF  file  and
  3564.         select "Close window after execution".  The environment variables
  3565.         CFTNBASE,  CSTNBASE and CXTNBASE are used in the same way  as  in
  3566.         the  BRIEF version.  Key-assignments to macro procedure names are
  3567.         not performed,  if you prefer hot-keys,  you are free to do  this
  3568.         for yourself.
  3569.  
  3570.         In the MicroEMACS WINDOWS version,  however,  the user accessible
  3571.         macros can be integrated into the "Miscellaneous" pull-down  menu
  3572.         (thanks  to  the  incredible  macro  programming  capabilities of
  3573.         MicroEMACS!).   To  view  the  generated  output  file  with  its
  3574.         semigraphic  frames,  change the font type and select for example
  3575.         the 'TERMINAL'  font  from  the  OEM  font  list  which  supports
  3576.         semigraphic characters.
  3577.  
  3578.  
  3579.  
  3580.  
  3581.  
  3582.  
  3583.  
  3584.  
  3585.  
  3586.  
  3587.  
  3588.  
  3589.  
  3590.  
  3591.  
  3592.  
  3593.  
  3594.  
  3595.  
  3596.  
  3597.  
  3598.  
  3599.                                      - 59 -
  3600.  
  3601.  
  3602.         12   TROUBLE SHOOTING
  3603.  
  3604.         This section contains informations about problems and the several
  3605.         reasons  which  may  occur during the use of SXT programs.  It is
  3606.         strictly  recommended  that  users  should  read   the   complete
  3607.         documentation  to have an overview about the features before they
  3608.         start using the programs and run into  any  unexpected  troubles.
  3609.         See also the chapter about 'PROGRAM LIMITATIONS'.
  3610.  
  3611.         A PROGRAM CANNOT BE EXECUTED
  3612.         The  program  path  is  not specified in the environment variable
  3613.         PATH,  the programs  are  not  yet  installed  in  the  specified
  3614.         directory,  attempt  to  start  a 386 protected mode version on a
  3615.         80286 (or lower) computer.
  3616.  
  3617.         EXECUTION STOPPED WITH MESSAGE "OUT OF MEMORY"
  3618.         An  attempt  to  allocate  memory  has  failed.   Try  to  remove
  3619.         unnecessary memory resident TSR programs and/or use the protected
  3620.         mode versions if you have an 386/486. If this message happens for
  3621.         the protected mode versions,  there is not enough free disk space
  3622.         for the swap file. Set the temporary directory,  defined by 'TMP'
  3623.         resp.   'TEMP'  environment  variables,   to  another  drive,  if
  3624.         possible.
  3625.  
  3626.         WRITING THE OUTPUT FILE TAKES A LONG TIME
  3627.         A large number of informations must be handled,  option -x or  -r
  3628.         is  not set and so the output tree chart is very large,  slow CPU
  3629.         and/or harddisk.  Use option -v to redirect intermediate files to
  3630.         a faster RAM-disk (if such is present).
  3631.  
  3632.         THE RESULTING OUTPUT IS DEEPLY NESTED AND EXCEEDS THE SCREEN SIZE
  3633.         Two  reasons: Use the -r or -x option if not already specified or
  3634.         the source code/data types are indeed deeply nested.
  3635.  
  3636.         THE BRIEF MACROS CANNOT BE EXECUTED
  3637.         The macro file is not loaded, other macros with the same names or
  3638.         assigned keys already exist.
  3639.  
  3640.         THE BRIEF OR MICROEMACS MACROS CANNOT BE LOADED
  3641.         The path to the  macro  file  location  must  be  specified  when
  3642.         loading the macros,  if they are not in the default directory for
  3643.         the editor.
  3644.  
  3645.         THE BRIEF MACROS DO NOT FIND ANY FUNCTIONS OR DATA TYPES
  3646.         There is no access to CFTN,  CSTN,  DFTN (...),  due to incorrect
  3647.         path  specification,  no  database  is  present,  the path to the
  3648.         database files is incorrect, the database name is incorrect.
  3649.  
  3650.         THE BYTE OFFSET CALCULATION FILE "CST_OFFS.C" CANNOT BE COMPILED
  3651.         Several reasons: Necessary data types or include  files  are  not
  3652.         specified or the CST processing was done with include files other
  3653.         than  those being used for compiling.  If the number of data type
  3654.         informations is too large,  some  compilers  cannot  compile  the
  3655.         large  number  of  statements in a single file generated from CST
  3656.         ('out of heap space',  'code segment too large' or other messages
  3657.  
  3658.  
  3659.  
  3660.                                      - 60 -
  3661.  
  3662.  
  3663.         like  that).  In  that  case  you may have to split the file into
  3664.         several smaller files or reduce  the  number  of  data  types  to
  3665.         display.
  3666.  
  3667.         LOCATING ITEMS IN THE BRIEF EDITOR POINTS TO WRONG PLACES
  3668.         Searching  items  from  within  the  BRIEF editor points to wrong
  3669.         lines,  the requested item is not present there or the file seems
  3670.         to  be corrupted.  This can have several reasons: The file is not
  3671.         up-to-date and has been changed since the database generation  so
  3672.         that the line references are no longer valid.  Another reason can
  3673.         be that the source file has explicit #line numbers as it is usual
  3674.         for files produced by source code generators like  YACC/BISON  or
  3675.         LEX/FLEX.  A  third  reason  may  be  that  the  source  file was
  3676.         generated on an UNIX system and has therefore only LF instead  of
  3677.         CR+LF  as  end-of-line delimiter so that BRIEF cannot display the
  3678.         file correctly, the file seems to be written in a single line.
  3679.  
  3680.         UNEXPECTED RESULTS WHILE  RUNNING  THE  TEXT  MODE  COMMAND  LINE
  3681.         VERSIONS UNDER WINDOWS 3.1
  3682.         The 386 versions cannot run under Windows 3.1, they are using the
  3683.         CPU  exclusive and can therefore not co-exist with Windows,  only
  3684.         the real mode versions can. In Windows enhanced mode (virtual 386
  3685.         mode),  the real  mode  versions  cannot  run  simultaneously  in
  3686.         several  independent  DOS-windows if they are working in the same
  3687.         directory or  use  the  same  temporary  directory,  because  the
  3688.         temporary  intermediate  files  may  have the same names and will
  3689.         conflict due to multiple accesses to the same file. This may also
  3690.         happen if the same files are scanned.
  3691.  
  3692.         MICROEMACS FOR WINDOWS SEEMS TO HANG DURING DATABASE  ACCESS  AND
  3693.         DOES NOT RETURN
  3694.         The reason is usually quite simple: The shell call to DOS through
  3695.         DOSEXEC.PIF  waits  for  a keystroke to continue execution and to
  3696.         return to WINDOWS.  You may change this behaviour by editing  the
  3697.         DOSEXEC.PIF    file   (see   MicroEMACS   section   for   further
  3698.         information).
  3699.  
  3700.  
  3701.  
  3702.  
  3703.  
  3704.  
  3705.  
  3706.  
  3707.  
  3708.  
  3709.  
  3710.  
  3711.  
  3712.  
  3713.  
  3714.  
  3715.  
  3716.  
  3717.  
  3718.  
  3719.  
  3720.  
  3721.                                      - 61 -
  3722.  
  3723.  
  3724.         13   FREQUENTLY ASKED QUESTIONS (FAQ)
  3725.  
  3726.         ARE THERE ANY RESTRICTIONS IN THE USE OF THE ANALYSIS RESULTS?
  3727.         No restrictions for registered users,  they can use  the  results
  3728.         for all purposes like program documentation, customer information
  3729.         or  debugging  as long as a notice about the name of the used SXT
  3730.         program given.
  3731.  
  3732.         WHY ARE SEVERAL DATABASE FILES FOR EVERY PROJECT GENERATED?
  3733.         Separating the analysis  items  (identifier  names,  file  names,
  3734.         relationships,  ...)  of one project into several closely related
  3735.         database files  is  the  best  way  to  achieve  minimum  storage
  3736.         requirements and to optimise disk usage.  This way of storage has
  3737.         no redundancies compared to storage in a single database file.
  3738.  
  3739.         WHY IS THERE NO CROSS REFERENCE FOR VARIABLES INCLUDED?
  3740.         This would  need  much  additional  memory  and  slows  down  the
  3741.         analysis  process.  There would also be a lot of multiple defined
  3742.         names in different contexts to be managed if  several  files  are
  3743.         analysed. There also exist a lot of tools which perform this task
  3744.         quite good.
  3745.  
  3746.         WHY ARE CFT AND CST NOT COMBINED IN ONE PROGRAM?
  3747.         Historical and practical reasons: the CFT development was started
  3748.         before  CST and both programs are optimised for their own special
  3749.         purposes.  Combining them would complicate them and slow down the
  3750.         analysis process. Also the memory requirements would grow.
  3751.  
  3752.  
  3753.  
  3754.  
  3755.  
  3756.  
  3757.  
  3758.  
  3759.  
  3760.  
  3761.  
  3762.  
  3763.  
  3764.  
  3765.  
  3766.  
  3767.  
  3768.  
  3769.  
  3770.  
  3771.  
  3772.  
  3773.  
  3774.  
  3775.  
  3776.  
  3777.  
  3778.  
  3779.  
  3780.  
  3781.  
  3782.                                      - 62 -
  3783.  
  3784.  
  3785.         14   REFERENCES
  3786.  
  3787.         Brian  W.  Kernighan,  Dennis  M.  Ritchie:  "The  C  Programming
  3788.         Language", Prentice Hall, Englewood Cliffs, Second Edition 1988
  3789.  
  3790.         Samuel P. Harbison,  Guy L.  Steele Jr.: "C: A Reference Manual",
  3791.         Prentice Hall, Englewood Cliffs, Third Edition 1991
  3792.  
  3793.         Bjarne    Stroustrup:    "The    C++    Programming    Language",
  3794.         Addison-Wesley, Second Edition 1992
  3795.  
  3796.         Margaret  A.   Ellis,   Bjarne  Stroustrup:  "The  Annotated  C++
  3797.         Reference Manual" (ARM), Addison-Wesley, Second Edition 1991
  3798.  
  3799.         "Rationale for American National Standard for Information Systems
  3800.         - Programming Language C" (can be obtained via anonymous FTP from
  3801.         ftp.uu.net in '/doc/standards/ansi/X3.159-1989/ratinale.PS.Z')
  3802.  
  3803.         "Working  Paper  for  Draft  Proposed  International Standard for
  3804.         Information Systems  -  Programming  Language  C++",  AT&T,  ANSI
  3805.         committee X3J16, ISO working group WG21, January 28, 1993
  3806.  
  3807.         Bjarne Stroustrup, Keith Gorlen, Phil Brown, Dennis Mancl, Andrew
  3808.         Koenig: "UNIX System V - AT&T C++ Language System,  Release 2.1 -
  3809.         Selected Readings", AT&T, 1989
  3810.  
  3811.         Goldberg,  A.: "Programmer as Reader",  IEEE Software,  September
  3812.         1987
  3813.  
  3814.         L.W.  Cannon,  R.A.  Elliot,  L.W.  Kirchhoff,  J.H. Miller, J.M.
  3815.         Milner, R.W. Mitze, E.P. Schan, N.O. Whittington, H. Spencer,  D.
  3816.         Keppel,  M.  Brader:  "Recommended C Style and Coding Standards",
  3817.         Technical Report, in the Public Domain,  Revision 6.0,  July 1991
  3818.         (revised  and  updated  version  of  the  'AT&T Indian Hill style
  3819.         guide',  can be obtained via anonymous FTP from cs.washington.edu
  3820.         in '~ftp/pub/cstyle.tar.Z')
  3821.  
  3822.         A.  Dolenc,  A. Lemmke, D. Keppel, G.V. Reilly: "Notes on Writing
  3823.         Portable Programs in C", Technical Report,  in the Public Domain,
  3824.         Revision 8, November 1990 (can be obtained via anonymous FTP from
  3825.         cs.washington.edu in '~ftp/pub/cport.tar.Z')
  3826.  
  3827.         M.   Henricson,  E.  Nyquist:  "Programming  in  C++,  Rules  and
  3828.         Recommendations",   Technical  Report,   in  the  Public  Domain,
  3829.         Ellemtel  Telecommunication Systems Laboratories,  Alvsjo/Sweden,
  3830.         Document No. M 90 0118 Uen, Rev. C (can be obtained via anonymous
  3831.         FTP from various sites as 'rules.ps.Z' or 'c++rules.ps.Z')
  3832.  
  3833.         H. Wehnes: "FORTRAN 77", 3. Auflage, Carl Hanser Verlag, 1984
  3834.  
  3835.         H.   Sigl:  "dBase/Foxbase/Clipper  -  Globalreferenz",   Addison
  3836.         Wesley, 1989
  3837.  
  3838.         Compiler  reference  manuals and related documentations (language
  3839.         references, language implementations and extensions):
  3840.  
  3841.  
  3842.  
  3843.                                      - 63 -
  3844.  
  3845.  
  3846.         -    Microsoft C 5.1
  3847.         -    Microsoft C 6.0
  3848.         -    Microsoft C/C++ 7.0
  3849.         -    Microsoft VC++ 1.5 Professional
  3850.         -    Microsoft C/C++ for Windows NT (Beta Release March 1993)
  3851.         -    Microsoft VC++ 1.0 for Windows NT (Beta Release June 1993)
  3852.         -    Microsoft VC++ 1.1 for Windows NT
  3853.         -    Microsoft C for SCO UNIX System V Rel. 3.2
  3854.         -    Microsoft Macro Assembler MASM 5.1
  3855.         -    Borland Turbo C++ 1.0
  3856.         -    Borland C++ 2.0
  3857.         -    Borland C++ 3.1
  3858.         -    Borland C++ 1.0 for OS/2
  3859.         -    Borland Turbo Assembler TASM 2.0
  3860.         -    Intel 80860 Metaware High C i860 APX (UNIX-hosted)
  3861.         -    Intel 80960 C-Compiler (ic960, ec960)
  3862.         -    Intel 80960 Assembler (asm960)
  3863.         -    GNU-960 Tools (UNIX-hosted)
  3864.         -    GNU-C Compiler 2.2.2/ 2.4.5/ 2.5.7  (C,  C++,  Objective-C),
  3865.              GNU-C DOS and OS/2 ports (DJGPP, EMX)
  3866.         -    GNU Assembler
  3867.         -    AT&T  C++  2.1  CFRONT  (C++  to  C translator) for SCO UNIX
  3868.              System V Rel. 3.2
  3869.         -    IBM C-Compilers (CC,  XLC) for IBM RS  6000  RISC  stations,
  3870.              AIX 3.15
  3871.         -    HP  C-Compilers (CC,  C89) for HP Apollo 9000 RISC stations,
  3872.              HP-UX 9.0
  3873.         -    SUN SunOS 4.1 C-Compiler
  3874.         -    Digital Equipment Corporation (DEC) VAX C
  3875.         -    Digital Equipment Corporation (DEC) VAX FORTRAN
  3876.         -    Ashton Tate dBase III plus
  3877.  
  3878.  
  3879.  
  3880.  
  3881.  
  3882.  
  3883.  
  3884.  
  3885.  
  3886.  
  3887.  
  3888.  
  3889.  
  3890.  
  3891.  
  3892.  
  3893.  
  3894.  
  3895.  
  3896.  
  3897.  
  3898.  
  3899.  
  3900.  
  3901.  
  3902.  
  3903.  
  3904.                                      - 64 -
  3905.  
  3906.  
  3907.         15   TRADEMARKS
  3908.  
  3909.         All brand or product names  are  trademarks  (TM)  or  registered
  3910.         trademarks (R) of their respective owners.
  3911.  
  3912.         The  following  products  and  names  are  Copyright  (C) Juergen
  3913.         Mueller (J.M.), all rights reserved world-wide:
  3914.  
  3915.              CXT (TM) C EXPLORATION TOOLS
  3916.              CFT (TM) C FUNCTION TREE GENERATOR
  3917.              CFTN (TM) C FUNCTION TREE NAVIGATOR
  3918.              CST (TM) C STRUCTURE TREE GENERATOR
  3919.              CSTN (TM) C STRUCTURE TREE NAVIGATOR
  3920.  
  3921.              CXTWIN (TM) C EXPLORATION TOOLS for Windows
  3922.              CFTWIN (TM) C FUNCTION TREE GENERATOR for Winfows
  3923.              CSTWIN (TM) C STRUCTURE TREE GENERATOR for Windows
  3924.  
  3925.              DXT (TM) DBASE EXPLORATION TOOLS
  3926.              DFT (TM) DBASE FUNCTION TREE GENERATOR
  3927.              DFTN (TM) DBASE FUNCTION TREE NAVIGATOR
  3928.  
  3929.              DXTWIN (TM) DBASE EXPLORATION TOOLS for Windows
  3930.              DFTWIN (TM) DBASE FUNCTION TREE GENERATOR for Windows
  3931.  
  3932.              FXT (TM) FORTRAN EXPLORATION TOOLS
  3933.              FFT (TM) FORTRAN FUNCTION TREE GENERATOR
  3934.              FFTN (TM) FORTRAN FUNCTION TREE NAVIGATOR
  3935.  
  3936.              FXTWIN (TM) FORTRAN EXPLORATION TOOLS for Windows
  3937.              FFTWIN (TM) FORTRAN FUNCTION TREE GENERATOR for Windows
  3938.  
  3939.              LXT (TM) LISP EXPLORATION TOOLS
  3940.              LFT (TM) LISP FUNCTION TREE GENERATOR
  3941.              LFTN (TM) LISP FUNCTION TREE NAVIGATOR
  3942.  
  3943.              LXTWIN (TM) LISP EXPLORATION TOOLS for Windows
  3944.              LFTWIN (TM) LISP FUNCTION TREE GENERATOR for Windows
  3945.  
  3946.         These packages are part of
  3947.  
  3948.              SXT (TM) SOFTWARE EXPLORATION TOOLS
  3949.              SXTWIN (TM) SOFTWARE EXPLORATION TOOLS for Windows
  3950.  
  3951.         which provide a similar set of  functionalities  for  the  source
  3952.         code analysis of different programming languages.
  3953.  
  3954.         See  PRODUCT.DOC  for a complete overview of the SXT packages and
  3955.         the different supported platforms.
  3956.  
  3957.  
  3958.  
  3959.  
  3960.  
  3961.  
  3962.  
  3963.  
  3964.  
  3965.                                      - 65 -
  3966.  
  3967.  
  3968.         APPENDIX 1: C-PRECOMPILER DEFINES
  3969.  
  3970.         The  following  list  shows  the  precompiler  defines  for   the
  3971.         supported  compiler  types  (option -T).  It contains the default
  3972.         defines and the optional memory model and architecture defines.
  3973.  
  3974.         Other default compiler defines which are usually declared by some
  3975.         of the compilers are not automatically defined by the -T  option.
  3976.         These  are  defines  for  compilation like WINDOWS,  __WINDOWS__,
  3977.         _Windows,  DLL or __DLL__,  for optimization like __OPTIMIZE__ or
  3978.         __FASTCALL__  or  others  like  those  about  target (operating-)
  3979.         systems like NT, MIPS,  UNIX,  unix,  __unix__,  i386,  __i386__,
  3980.         GNUDOS,  BSD,  VMS, USG, DGUX or hpux. Other sometimes predefined
  3981.         macros are __STRICT_ANSI__ or  __CHAR_UNSIGNED__.  If  necessary,
  3982.         they can be user defined on the command line with the -D option.
  3983.  
  3984.         The  macro  name  __cplusplus will be defined if the command line
  3985.         option '-C++' is set to enable C++ processing.
  3986.  
  3987.         1. MSC51 (Microsoft C 5.1):
  3988.         Default defines:         MSDOS, M_I86
  3989.         C++ specific defines:    (none)
  3990.         Memory model defines:    M_I86SM, M_I86MM, M_I86CM, M_I86LM,
  3991.                                  M_I86HM
  3992.  
  3993.         2. MSC70 (Microsoft C/C++ 7.0):
  3994.         Default defines:         MSDOS, M_I86, _MSC_VER (=700)
  3995.         C++ specific defines:    (none)
  3996.         Memory model defines:    M_I86TM, M_I86SM, M_I86MM, M_I86CM,
  3997.                                  M_I86LM, M_I86HM
  3998.  
  3999.         3. MSVC15 (Microsoft Visual C++ 1.5):
  4000.         Default defines:         MSDOS, M_I86, _MSC_VER (=800)
  4001.         C++ specific defines:    (none)
  4002.         Memory model defines:    M_I86TM, M_I86SM, M_I86MM, M_I86CM,
  4003.                                  M_I86LM, M_I86HM
  4004.  
  4005.         4. MSVCWNT (Microsoft Visual C++ 1.0 for Windows NT):
  4006.         Default defines:         MSDOS, M_I86, _MSC_VER (=800),
  4007.                                  _M_IX86 (=300)
  4008.         C++ specific defines:    (none)
  4009.         Memory model defines:    (not necessary)
  4010.  
  4011.         5. TC10 (Borland Turbo C++ 1.0):
  4012.         Default defines:         __MSDOS__, __TURBOC__
  4013.         C++ specific defines:    __TCPLUSPLUS
  4014.         Memory model defines:    __TINY__, __SMALL__, __MEDIUM__,
  4015.                                  __COMPACT_, __LARGE__, __HUGE__
  4016.  
  4017.         6. BC20 (Borland C++ 2.0):
  4018.         Default defines:         __MSDOS__, __BORLANDC__ (=0x0200),
  4019.                                  __TURBOC__ (=0x0297)
  4020.         C++ specific defines:    __BCPLUSPLUS__ (=0x0200),
  4021.                                  __TCPLUSPLUS__ (=0x0200)
  4022.         Memory model defines:    __TINY__, __SMALL__, __MEDIUM__,
  4023.                                  __COMPACT_, __LARGE__, __HUGE__
  4024.  
  4025.  
  4026.                                      - 66 -
  4027.  
  4028.  
  4029.  
  4030.         7. BC31 (Borland C++ 3.1):
  4031.         Default defines:         __MSDOS__, __BORLANDC__ (=0x0410),
  4032.                                  __TURBOC__ (=0x0410)
  4033.         C++ specific defines:    __BCPLUSPLUS__ (=0x0310),
  4034.                                  __TCPLUSPLUS__ (=0x0310)
  4035.         Memory model defines:    __TINY__, __SMALL__, __MEDIUM__,
  4036.                                  __COMPACT_, __LARGE__, __HUGE__
  4037.  
  4038.         8. BC10OS2 (Borland C++ 1.0 for OS/2):
  4039.         Default defines:         __OS2__, __BORLANDC__ (=0x0400),
  4040.                                  __TURBOC__ (=0x0400)
  4041.         C++ specific defines:    __BCPLUSPLUS__ (=0x0320),
  4042.                                  __TCPLUSPLUS__ (=0x0320),
  4043.                                  __TEMPLATES__
  4044.         Memory model defines:    (not necessary)
  4045.  
  4046.         9. GNU (GNU C 2.2.2):
  4047.         Default defines:         __GNUC__ (=2)
  4048.         C++ specific defines:    __GNUG__ (=2)
  4049.         Memory model defines:    (not necessary)
  4050.  
  4051.         10. I960 (Intel iC960 3.0):
  4052.         Default defines:         __i960
  4053.         C++ specific defines:    (none)
  4054.         Memory model defines:    (not necessary)
  4055.         Architecture defines:    __i960KA, __i960KB, __i960SA, __i960SB,
  4056.                                  __i960MC, __i960CA
  4057.  
  4058.  
  4059.  
  4060.  
  4061.  
  4062.  
  4063.  
  4064.  
  4065.  
  4066.  
  4067.  
  4068.  
  4069.  
  4070.  
  4071.  
  4072.  
  4073.  
  4074.  
  4075.  
  4076.  
  4077.  
  4078.  
  4079.  
  4080.  
  4081.  
  4082.  
  4083.  
  4084.  
  4085.  
  4086.  
  4087.                                      - 67 -
  4088.  
  4089.  
  4090.         APPENDIX 2: RESERVED C/C++ KEYWORDS
  4091.  
  4092.         The following list shows the keywords being recognised by CFT and
  4093.         CST,   the  standard  C  keywords,   the  C++  keywords  and  the
  4094.         non-standard  keywords which are compiler dependent extensions to
  4095.         the C or C++ language. Standard C keywords are also C++ keywords,
  4096.         always!  The C++ keywords are recognised only if option '-C++' is
  4097.         set, otherwise they are treated as identifiers. This list may not
  4098.         be  complete  or  correct  due  to  upcoming  new releases of the
  4099.         supported compilers with new  extensions  or  extensions  to  the
  4100.         language  standard.  C++,  for  which till now no 'real' language
  4101.         standard exists (except the de-facto standard,  the  AT&T  CFRONT
  4102.         implementation),    differs    among   several   implementations,
  4103.         especially for the new introduced exception and template concepts
  4104.         (try,  catch,  throw,  template).   Extensions  to  the  language
  4105.         especially  in  GNU  C  (e.g.  __alignof,  __classof,  interface,
  4106.         signature,  __FUNCTION__,  ...) or undocumentd features  e.g.  in
  4107.         Microsoft  C/C++  7.0 are ignored (even if they are listed here).
  4108.         This list may not be complete or correct.
  4109.  
  4110.         KEYWORDS       Standard       MSC TC/BC GNU C
  4111.                        C    C++       7.0 3.0   2.2.2
  4112.  
  4113.         asm            x
  4114.         auto           x
  4115.         break          x
  4116.         case           x
  4117.         catch               x         (x)       x
  4118.         cdecl                         x    x
  4119.         char           x
  4120.         class               x
  4121.         classof                                 x
  4122.         const          x
  4123.         continue       x
  4124.         default        x
  4125.         delete              x
  4126.         do             x
  4127.         double         x
  4128.         dynamic                                 x
  4129.         else           x
  4130.         enum           x
  4131.         except                                  x
  4132.         exception                               x
  4133.         extern         x
  4134.         far                           x    x
  4135.         float          x
  4136.         for            x
  4137.         fortran                       x    x
  4138.         friend              x
  4139.         goto           x
  4140.         huge                          x    x
  4141.         if             x
  4142.         inline              x
  4143.         int            x
  4144.         interrupt                     x    x
  4145.         long           x
  4146.  
  4147.  
  4148.                                      - 68 -
  4149.  
  4150.  
  4151.         near                          x    x
  4152.         new                 x
  4153.         operator            x
  4154.         overload                           x    x
  4155.         pascal                        x    x
  4156.         private             x
  4157.         protected           x
  4158.         public              x
  4159.         register       x
  4160.         return         x
  4161.         short          x
  4162.         signed         x
  4163.         sizeof         x
  4164.         static         x
  4165.         struct         x
  4166.         switch         x
  4167.         template            x
  4168.         this                x
  4169.         throw               x
  4170.         try                 x         (x)       x
  4171.         typedef        x
  4172.         typeof                                  x
  4173.         union          x
  4174.         unsigned       x
  4175.         virtual             x
  4176.         void           x
  4177.         volatile       x
  4178.         while          x
  4179.         __alignof                               x
  4180.         __alignof__                             x
  4181.         __asm                         x         x
  4182.         __asm__                                 x
  4183.         __attribute                             x
  4184.         __attribute__                           x
  4185.         __based                       x
  4186.         __cdecl                       x
  4187.         __classof                               x
  4188.         __classof__                             x
  4189.         __const                       x         x
  4190.         __const__                               x
  4191.         __emit                        x
  4192.         __except                      x
  4193.         __export                      x
  4194.         __extension__                           x
  4195.         __far                         x
  4196.         __fastcall                    x
  4197.         __finally                     x
  4198.         __fortran                     x
  4199.         __headof                                x
  4200.         __headof__                              x
  4201.         __huge                        x
  4202.         __inline                                x
  4203.         __inline__                              x
  4204.         __interrupt                   x
  4205.         __label__                               x
  4206.         __loadds                      x
  4207.  
  4208.  
  4209.                                      - 69 -
  4210.  
  4211.  
  4212.         __near                        x
  4213.         __saveregs                    x
  4214.         __segment                     x
  4215.         __segname                     x
  4216.         __self                        x
  4217.         __signed                                x
  4218.         __signed__                              x
  4219.         __stdcall                     x
  4220.         __syscall                     x
  4221.         __try                         x
  4222.         __typeof                                x
  4223.         __typeof__                              x
  4224.         __volatile                              x
  4225.         __volatile__                            x
  4226.         _asm                          x
  4227.         _based                        x
  4228.         _cdecl                        x
  4229.         _emit                         x
  4230.         _export                       x    x
  4231.         _far                          x
  4232.         _fastcall                     x
  4233.         _fortran                      x
  4234.         _huge                         x
  4235.         _interrupt                    x
  4236.         _loadds                       x    x
  4237.         _near                         x
  4238.         _pascal                       x
  4239.         _saveregs                     x    x
  4240.         _seg                               x
  4241.         _segment                      x
  4242.         _segname                      x
  4243.         _self                         x
  4244.  
  4245.  
  4246.  
  4247.  
  4248.  
  4249.  
  4250.  
  4251.  
  4252.  
  4253.  
  4254.  
  4255.  
  4256.  
  4257.  
  4258.  
  4259.  
  4260.  
  4261.  
  4262.  
  4263.  
  4264.  
  4265.  
  4266.  
  4267.  
  4268.  
  4269.  
  4270.                                      - 70 -
  4271.  
  4272.  
  4273.         APPENDIX 3: RESERVED FORTRAN KEYWORDS
  4274.  
  4275.         The following lists show the  keywords  and  intrinsic  functions
  4276.         from FORTRAN 77 and non-standard extensions (VAX, CDC, AIX, UNIX,
  4277.         ...) recognised by FFT. This list may not be complete or correct.
  4278.  
  4279.         Keywords: ACCEPT, ASSIGN, AUTOMATIC, BACKSPACE, BLOCKDATA, BLOCK,
  4280.         BYTE,  CALL,  CHARACTER,  CLOSE, COMMON, COMPLEX, CONTINUE, DATA,
  4281.         DIMENSION, DOUBLECOMPLEX, DOUBLEPRECISION, DOUBLE,  DOWHILE,  DO,
  4282.         ELSEIF,  ELSE,  ENDDO,  ENDFILE,  ENDIF, END, ENTRY, EQUIVALENCE,
  4283.         EXTERNAL,  FILE,  FORMAT,  FUNCTION,  GOTO,  GO,  IF,   IMPLICIT,
  4284.         INCLUDE,  INQUIRE,  INTEGER,  INTRINSIC, LOGICAL, NAMELIST, NONE,
  4285.         OPEN, PARAMETER, PAUSE, PRECISION, PRINT, PROGRAM,  PUNCH,  READ,
  4286.         REAL,  RETURN,  REWIND, SAVE, STATIC, STOP, SUBROUTINE, THEN, TO,
  4287.         TYPE, WHILE, WRITE,
  4288.  
  4289.         Non-standard  keywords:  ASSERT,  DELETE,   DICTIONARY,   ENDMAP,
  4290.         ENDSTRUCTURE,   ENDUNION,  IMPLICITNONE,  MAP,  POINTER,  RECORD,
  4291.         REWRITE, STRUCTURE, UNION, UNLOCK, VOLATILE
  4292.  
  4293.         Intrinsic functions: ABS, ACHAR, ACOS, AIMAG, AINT, ALOG10, ALOG,
  4294.         AMAX0, AMAX1, AMIN0, AMIN1, AMOD, AND, ANINT, ASIN, ATAN2,  ATAN,
  4295.         CABS,  CCOS,  CEXP,  CHAR,  CLOG,  CMPLX, CONJG, COSH, COS, CSIN,
  4296.         CSQRT, DABS, DACOS, DASIN, DATAN2, DATAN, DBLE,  DCMPLX,  DCONJG,
  4297.         DCOSH,  DCOS, DDIM, DEXP, DFLOAT, DIMAG, DIM, DINT, DLOG10, DLOG,
  4298.         DMAX1, DMIN1, DMOD, DNINT,  DPROD,  DSIGN,  DSINH,  DSIN,  DSQRT,
  4299.         DTANH,  DTAN,  EPBASE,  EPEMAX,  EPEMIN,  EPHUGE, EPMRSP, EPPREC,
  4300.         EPTINY, EXP,  FLOAT,  FPABSP,  FPEXPN,  FPFRAC,  FPMAKE,  FPRRSP,
  4301.         FPSCAL,  IABS,  IACHAR,  ICHAR,  IDIM, IDINT, IDNINT, IFIX, IMAG,
  4302.         INDEX, INT, ISIGN, LEN, LGE, LGT, LLE, LLT, LOG10,  LOG,  LSHIFT,
  4303.         MAX0,  MAX1,  MAX,  MIN0,  MIN1,  MIN,  MOD, NINT, NOT, OR, REAL,
  4304.         RSHIFT, SIGN, SINH, SIN, SNGL, SQRT, TANH, TAN, XOR, ZABS,  ZCOS,
  4305.         ZEXP, ZLOG, ZSIN, ZSQRT,
  4306.  
  4307.         Non-standard intrinsic functions: ABORT,  ACOSD,  ASIND,  ATAN2D,
  4308.         ATAND, BTEST, CABS1, CAMAX, CAMIN, CASUM,  CAXPY,  CCOPY,  CDABS,
  4309.         CDCOS,  CDEXP,  CDLOG,  CDOTC,  CDOTU, CDSIN, CDSQRT, CMAX, CMIN,
  4310.         CNORM2, CNRM2, CNRSQ, COSD, CROTG,  CROT,  CSCAL,  CSET,  CSIGN1,
  4311.         CSIGN,  CSUM,  CSWAP,  CVCAL,  CZAXPY, DAMAX, DAMIN, DASUM, DATE,
  4312.         DAXPY, DCOPY, DDOT, DMAX,  DMIN,  DNORM2,  DNRM2,  DNRSQ,  DREAL,
  4313.         DROTG,  DROT,  DSCAL,  DSET,  DSUM, DSWAP, DVCAL, DZAXPY, ERRSNS,
  4314.         EXIT, GETARG, GETENV,  GMTIME,  HFIX,  I,  IARGC,  IAND,  IBCHNG,
  4315.         IBCLR,  IBITS,  IBSET,  ICAMAX,  ICAMIN,  ICMAX,  ICMIN,  IDAMAX,
  4316.         IDAMIN, IDATE, IDMAX, IDMIN, IEOR,  IOR,  IQINT,  IQNINT,  IRAND,
  4317.         ISAMAX,  ISAMIN, ISHA, ISHC, ISHFT, ISHFTC, ISMAX, ISMIN, IZAMAX,
  4318.         IZAMIN,  IZMAX,  IZMIN,  JFIX,  LTIME,  MVBITS,  NWORKERS,  QEXT,
  4319.         QFLOAT,  RAN,  RAND,  SAMAX,  SAMIN,  SASUM,  SAXPY, SCOPY, SDOT,
  4320.         SECNDS, SIND, SIZEOF, SMAX, SMIN, SNORM2,  SNRM2,  SNRSQ,  SRAND,
  4321.         SROTG,  SROT,  SSCAL,  SSET,  SSUM, SSWAP, SVCAL, SYSTEM, SZAXPY,
  4322.         TAND, TIME, ZAMAX, ZAMIN,  ZASUM,  ZAXPY,  ZCOPY,  ZDOTC,  ZDOTU,
  4323.         ZEXT, ZMAX, ZMIN, ZNORM2, ZNRM2, ZNRSQ, ZROTG, ZROT, ZSCAL, ZSET,
  4324.         ZSUM, ZSWAP, ZVCAL, ZZAXPY
  4325.  
  4326.         VAX specific built-in functions: %DESCR, %LOC, %REF, %VAL
  4327.  
  4328.  
  4329.  
  4330.  
  4331.                                      - 71 -
  4332.  
  4333.  
  4334.         APPENDIX 4: EFFICIENCY
  4335.  
  4336.         To  provide some values about the speed and the efficiency of the
  4337.         programs, tests were performed with CFT386 and CST386.
  4338.  
  4339.         One test with CFT386 (v2.21) was done with the source code of the
  4340.         C++ part of the GNU-C compiler  (version  2.2.2),  which  is  the
  4341.         largest of the three compiler parts (C,  C++,  Objective-C).  The
  4342.         test was made on a 33 MHz 80486,  8 MB RAM,  256 KB cache,  12 ms
  4343.         hard  disk,  2.5  MB  RAM-disk.  The command line options were -m
  4344.         -rauspPC_INCLUDE_PATH -TGNU -cs -Cs -n -W5 -G  -vn:\  -L+  -time.
  4345.         The following results have been found:
  4346.  
  4347.         -    137  files  (71 source files and 66 include files) have been
  4348.              scanned
  4349.         -    a total number of 2318 functions has been found  from  which
  4350.              2236 functions were defined in the 69 source files
  4351.         -    the  directed  call  graph  would  have 2302 nodes and 10276
  4352.              connections
  4353.         -    the critical function call path has a maximum nesting  level
  4354.              of 115
  4355.         -    the  total  size  of  the  137 files is 6.538 MB with 208900
  4356.              lines (about  31  bytes/line),  source  code/filesize  ratio
  4357.              0.712, average function size is 1956 bytes resp. 63 lines
  4358.         -    the  effective  size  of the preprocessed and scanned source
  4359.              code (source files and their included files)  is  20.990  MB
  4360.              with 602300 lines
  4361.         -    the resulting output file has about 3.921 MB and 36000 lines
  4362.         -    the resulting 6 database files have a size of 870 KB (source
  4363.              code/database ratio is about 7.5 : 1)
  4364.         -    inside  BRIEF,  a  database  search  for  the  location of a
  4365.              function is performed in less than 4 seconds
  4366.         -    the total time  for  the  complete  processing  was  21'57''
  4367.              minutes  (11'03''  for preprocessing,  8'13'' for analysing,
  4368.              1'00'' for output file writing, 1'32'' for database writing)
  4369.         -    the average speed for  this  source  code  was  about  1.080
  4370.              MB/min. respectively 31000 lines/min.
  4371.  
  4372.         Another test with CFT386 (v2.21) was done with a large commercial
  4373.         project.  The test was made on a 33 MHz 80486,  8 MB RAM,  256 KB
  4374.         cache,  12 ms hard disk,  no RAM-disk.  The command line  options
  4375.         were  -m+  -rausp -cs -Cs -n -time -cmdline -M -G -TMSC70,L -P -L
  4376.         -W5. The results:
  4377.  
  4378.         -    291 files (194 source files and 97 include files) have  been
  4379.              scanned
  4380.         -    a  total  number of 1955 functions has been found from which
  4381.              1866 functions were defined in the source files
  4382.         -    the total size of the 291 files is  15.719  MB  with  387600
  4383.              lines,  source  code/filesize ratio 0.531,  average function
  4384.              size is 2800 bytes resp. 100 lines
  4385.         -    the effective size of the preprocessed  and  scanned  source
  4386.              code  (source  files and their included files) is 220.685 MB
  4387.              with 2861000 lines
  4388.  
  4389.  
  4390.  
  4391.  
  4392.                                      - 72 -
  4393.  
  4394.  
  4395.         -    the total time for  the  complete  processing  was  161'02''
  4396.              minutes (139'43'' for preprocessing,  19'21'' for analysing,
  4397.              0'56'' for output file writing, 0'58'' for database writing)
  4398.         -    the average speed for  this  source  code  was  about  1.388
  4399.              MB/min. respectively 17990 lines/min.
  4400.  
  4401.         To  get  some  efficiency values for CST386 (v2.21),  the include
  4402.         files from another commercial  project  were  analysed  for  data
  4403.         types.  The  test  was made on a 33 MHz 80486,  8 MB RAM,  256 KB
  4404.         cache, 12 ms hard disk, no RAM-disk:
  4405.  
  4406.         -    52 include files have been scanned
  4407.         -    a total number of 605 data types have been found from  which
  4408.              567  structures/unions  were defined in 42 of the 54 include
  4409.              files
  4410.         -    the directed call  graph  would  have  588  nodes  and  1787
  4411.              connections
  4412.         -    the  total size of the 52 files is 1.384 MB with 25410 lines
  4413.              (about 54 bytes/line), source code/filesize ratio 0.342
  4414.         -    the resulting output file (options -rasp  -cs  -Cs  -n)  has
  4415.              about 378 KB and 8760 lines
  4416.         -    the resulting 6 database files have a size of 315 KB (source
  4417.              code/database ratio is about 4.4 : 1)
  4418.         -    the  total  time  for  the  complete  processing  was 0'43''
  4419.              minutes (0'17'' for analysis, 0'05'' for output file writing
  4420.              and 0'20'' for database writing)
  4421.         -    the average speed for  this  source  code  was  about  4.885
  4422.              MB/min.  respectively  89700  lines/min  (only analysis,  no
  4423.              preprocessing performed).
  4424.  
  4425.         Another test with CST386 (v2.21) was done  with  the  C++  source
  4426.         code  of  the Microsoft Foundation Class (MFC) 2.0.  The test was
  4427.         made on a 33 MHz 80486, 8 MB RAM, 256 KB cache,  12 ms hard disk,
  4428.         2.5   MB   RAM-disk.   The   command   line  options  were  -rasp
  4429.         -I\msvc\mfc\include -I\msvc\include -P -TMSVCWNT -C++  -D_WINDOWS
  4430.         -D_X86_  -Cs -n -b -W5 -time -G -vn:\ -L+.  The following results
  4431.         have been found:
  4432.  
  4433.         -    170 files (95 source files and 75 include files)  have  been
  4434.              scanned
  4435.         -    a  total number of 890 data types have been found from which
  4436.              701 were defined in the source and include files
  4437.         -    the directed call  graph  would  have  755  nodes  and  1402
  4438.              connections
  4439.         -    the  total size of the 170 files is 2.42 MB with 87500 lines
  4440.              (about 28 bytes/line), source code/filesize ratio 0.779
  4441.         -    the effective size of the preprocessed  and  scanned  source
  4442.              code  (source  files  and their included files) is 157.28 MB
  4443.              with 5580100 lines
  4444.         -    the total time for  the  complete  processing  was  106'20''
  4445.              minutes  (72'07''  for preprocessing,  33'14'' for analysis,
  4446.              0'12'' for output file writing, 0'44'' for database writing)
  4447.         -    the average speed  for  this  source  code  was  about  1.49
  4448.              MB/min. respectively 53000 lines/min.
  4449.  
  4450.  
  4451.  
  4452.  
  4453.                                      - 73 -
  4454.  
  4455.  
  4456.         The  calculated  average values for the analysis speed differ due
  4457.         to the effective size of the  'really'  present  source  code  in
  4458.         relation  to  the  size  of the comments which can be seen by the
  4459.         code/filesize ratio.  The speed values do not consider  that,  if
  4460.         the  preprocessing  option  -P  is set,  the source code is first
  4461.         preprocessed to a temporary file and then analysed  in  a  second
  4462.         step  so  that  large  parts  of  the  source code are read twice
  4463.         (original and preprocessed code) and written  once  (intermediate
  4464.         preprocessor output).
  4465.  
  4466.         With these facts in mind, the analysis speed of CFT and CST seems
  4467.         to be quite acceptable!
  4468.  
  4469.  
  4470.  
  4471.         APPENDIX 5: REVIEWS
  4472.  
  4473.         CXT: The C Users Journal (Volume 12, Number 1, January 1994)
  4474.  
  4475.  
  4476.  
  4477.  
  4478.  
  4479.  
  4480.  
  4481.  
  4482.  
  4483.  
  4484.  
  4485.  
  4486.  
  4487.  
  4488.  
  4489.  
  4490.  
  4491.  
  4492.  
  4493.  
  4494.  
  4495.  
  4496.  
  4497.  
  4498.  
  4499.  
  4500.  
  4501.  
  4502.  
  4503.  
  4504.  
  4505.  
  4506.  
  4507.  
  4508.  
  4509.  
  4510.  
  4511.  
  4512.  
  4513.  
  4514.                                      - 74 -
  4515.  
  4516.  
  4517.         APPENDIX 6: SYSTEM REQUIREMENTS
  4518.  
  4519.         DOS real mode versions:
  4520.         -    IBM-AT or 100% compatible with Intel 80286 or higher, 640 KB
  4521.              RAM, hard-disk, DOS 3.3 or higher
  4522.  
  4523.         DOS protected mode versions:
  4524.         -    IBM-AT  or 100% compatible with Intel 80386/80387 or higher,
  4525.              4 MB RAM, hard-disk, DOS 3.3 or higher
  4526.  
  4527.         Windows 16 bit versions:
  4528.         -    IBM-AT or 100% compatible with Intel 80386 or higher,  4  MB
  4529.              RAM,  hard-disk,  Windows 3.1 or Windows for Workgroups 3.11
  4530.              (running in enhanced mode)
  4531.  
  4532.         Windows 32 bit (Win32s) versions:
  4533.         -    IBM-AT or 100% compatible with Intel 80386 or higher,  4  MB
  4534.              RAM,  hard-disk,  Windows  NT  3.1,  Windows  4.0 (Chicago),
  4535.              Windows 3.1 or  Windows  for  Workgroups  3.11  with  Win32s
  4536.              subsystem
  4537.  
  4538.  
  4539.  
  4540.         APPENDIX 7: INSTALLATION
  4541.  
  4542.         See INSTALL.DOC for informations.
  4543.  
  4544.  
  4545.  
  4546.  
  4547.                           (THIS DOCUMENT HAS 75 PAGES)
  4548.  
  4549.  
  4550.  
  4551.  
  4552.  
  4553.  
  4554.  
  4555.  
  4556.  
  4557.  
  4558.  
  4559.  
  4560.  
  4561.  
  4562.  
  4563.  
  4564.  
  4565.  
  4566.  
  4567.  
  4568.  
  4569.  
  4570.  
  4571.  
  4572.  
  4573.  
  4574.  
  4575.                                      - 75 -
  4576.